Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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!)

Examples:

  • <argument name> where { <argument name> | 0 <= <argument name> <= 255 }
  • <argument name> range: [0,255]
  • <argument name> is valid between zero and 255 inclusive.
share|improve this question
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 '11 at 21:41
    
@Ben Voigt, why assert (usually debug-only) when you can use Code Contracts? –  Job Aug 1 '11 at 22:54
    
@Job: Definitely do that, if your language supports them. But this question was tagged c++. –  Ben Voigt Aug 1 '11 at 23:21
add comment

migrated from stackoverflow.com Aug 1 '11 at 21:41

This question came from our site for professional and enthusiast programmers.

3 Answers

up vote 0 down vote accepted

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.

share|improve this answer
add comment

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".

share|improve this answer
add comment

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
Summary:
Retrieves a substring from this instance. The substring starts at a specified character position.

Parameters:
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.

Exceptions:
System.ArgumentOutOfRangeException: startIndex is less than zero or greater than the length of this instance.
share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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