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.

  • 9
    You MAY use these terms :-) Apr 14, 2016 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. Apr 14, 2016 at 18:00
  • 6
    @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. Apr 14, 2016 at 20:38
  • 3
    @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, 2016 at 20:45
  • 1
    @Kevin Nothing you can write will save you from Paula Bean.
    – user253751
    Jan 14, 2021 at 16:58

1 Answer 1



Precise terms are the best way to ensure the communication of an idea is understood. They remove ambiguity that can cause "defects" or can be used as wiggle room when some is trying to redefine a requirement on the fly.

  • @kevin yes I know it has been several years. : )
    – DrFloyd5
    Jan 14, 2021 at 3:05

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.