What is the appropriate method to describe a valid range of a parameter in the documentation of code? Obviously long-form documentation (white papers, API documents, etc) can be more verbose than the actual code but this is really to address issues in the actual code than in the distributed documentation (that every user should read to begin with!)


  • <argument name> where { <argument name> | 0 <= <argument name> <= 255 }
  • <argument name> range: [0,255]
  • <argument name> is valid between zero and 255 inclusive.
  • 4
    Why documentation? You can put it in the code, assert(x >= 0); assert(x <= 255); should get the message across very nicely, even to users who don't read the docs.
    – Ben Voigt
    Aug 1, 2011 at 21:41
  • @Ben Voigt, why assert (usually debug-only) when you can use Code Contracts?
    – Job
    Aug 1, 2011 at 22:54
  • @Job: Definitely do that, if your language supports them. But this question was tagged c++.
    – Ben Voigt
    Aug 1, 2011 at 23:21

3 Answers 3


If that's your valid range, I'd simply use a (signed) byte and let the compiler enforce it :-)

Otherwise, any documentation form that you are happy with, which is intuitively understandable by the reader, and is technically correct and clear, is fine. I'd go for something brief and universally understandable like (0 <= arg <= 255).

Another thing to consider is what does an out of range value cause to happen? In most cases, an out of range value will cause an effect (an assertion failure, a crash, an exception, an error return code, undefined behaviour?) so you may wish to document what will happen if an OOR input is provided. After all, you're documenting it so that callers know how to use it and what might happen if they get something wrong.


Use the constructs the language at hand gives you, because that is a good combination of being concise and understandable (to your audience, which are programmers). So for Python, you'd write "0 <= arg <= 255".


I would look for the source code of the core libraries in your language. Here is an example of Substring method of the String class in c#:

Public Function Substring(startIndex As Integer) As String
     Member of System.String
Retrieves a substring from this instance. The substring starts at a specified character position.

startIndex: The zero-based starting character position of a substring in this instance.

Return Values:
A string that is equivalent to the substring that begins at startIndex in this instance, or System.String.Empty if startIndex is equal to the length of this instance.

System.ArgumentOutOfRangeException: startIndex is less than zero or greater than the length of this instance.

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.