1

RFC 2119 defines several terms, including MUST, SHOULD, and MAY, for use in standards documents, particularly those relating to networking protocols such as IP and HTTP. These terms are widely used in RFCs to describe the requirement level of individual items in a specification (e.g. "the server MUST do X" or "the client MAY do Y").

Is it a good idea to document the requirements of an interface using RFC 2119? For example, a file-like interface might say this:

The .close() method SHOULD be called prior to program termination. After calling the .close() method, other methods in this interface MUST NOT be called.

(These statements probably seem obvious, but not all interfaces are so general-purpose. A special-purpose interface might have more interesting constraints.)

I like these terms because they provide an unambiguous yet terse description of what the interface requires, what it recommends, and what it permits, without getting into implementation details, and they can be used to constrain both the implementation and the client code. But I imagine they look rather weird to people unfamiliar with them, even if I do include the standard "this document uses RFC 2119" block of text.

  • 5
    You MAY use these terms :-) – Dan Pichelman Apr 14 '16 at 17:31
  • 2
    Note that RFC 2119 applies to RFC's, not general documentation. You can use the terms if you like, but they are not authoritative in anything but RFC's. – Robert Harvey Apr 14 '16 at 18:00
  • 5
    @RobertHarvey: You MAY however explicitly state in your documentation that users SHOULD interpret any occurrence of one of those terms in accordance with its definition in RFC2119 and that documentation authors MUST adhere to those definitions. You say they might look weird to people who are not familiar with them, but do those people actually exist? Are there practicing professional software developers who have never seen an RFC? I hope not, although after my years on SO, nothing surprises me anymore. – Jörg W Mittag Apr 14 '16 at 20:38
  • I certainly don't have any problem with such a declaration. – Robert Harvey Apr 14 '16 at 20:41
  • 1
    @JörgWMittag: I'm not concerned about real professionals. I'm concerned about Paula Bean who somehow got a job despite barely being able to throw rudimentary code together. – Kevin Apr 14 '16 at 20:45

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.