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.
6
You SHOULD.
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.
1