# Commenting/In-Code Documentation Styles

This might be a stupid question, but it's been in the back of my head for a while and I can't find a decent answer anywhere else.

I have a teacher who says we should explicitly list each parameter with a description, even if there's only one. This leads to a lot of repetition:

``````double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.
``````

When writing in-code documentation, how detailed are you?

-
your example is simplistic. In practice, you would specify far more constraints than just the type of the parameter, if it's an int, then it must be an integer that's been values X and Y. If the return value is a double, you can specify how precise it is, and how what values it can be (a function could exist that returns exactly 1.01, 2.31 and 5.01!). Be more specific and you won't see as much repetition... – omouse Feb 16 '12 at 7:25

## 7 Answers

For starters, I agree that the "Function:" line in your example is completely redundant. It's also been my experience that people taught in school to add that type of comment continue adding that type of comment in their production code.

Good comments don't repeat what's in the code. They answer the question "Why?" instead of "What?" or "How?" They cover expectations about the inputs, as well as how the code will behave under certain conditions. They cover why algorithm X was chosen instead of algorithm Y. In short, exactly the things that wouldn't be obvious to someone else1 from reading the code.

1: Someone else who is familiar with the language the code is written in. Don't write comments to teach, comment to supplement information.

-
+1, though make sure you remember that what is obvious to you may not be obvious to another programmer. – Josh K Dec 6 '10 at 19:37
@Josh: good point, so I edited the answer. – Larry Coleman Dec 6 '10 at 19:38
@Larry : Good comments should also include what: what goes in, what comes out, and especially which type goes in and out. – Joris Meys Dec 6 '10 at 21:33
@Joris: What goes in and what goes out is covered by "expectations about inputs" and "how the code will behave". As for which type goes in and out, I stand by what I said earlier: "Good comments don't repeat what's in the code." – Larry Coleman Dec 6 '10 at 22:01
@Larry: I rather read it in the comment than have to go through the declarations and the code every time I want to reuse a function. A matter of style I guess, I'm a lazy guy. – Joris Meys Dec 6 '10 at 22:09

Several languages have API document generation features like Ruby, Java, C# and C++ (via a command line tool). When you think about it in that way, it makes writing the API docs much more important. After all, it answers the question "how do I do ...?" So I won't do anything repetitive like `Function: MyFunction` when the name of the function is plain for everyone to see. The API doc generation tools are smart enough to do that for me. However, the following details are useful, particularly on public methods/functions:

• Summary (what it does and when relevant a summary of how to use it)
• List of parameters and what is expected
• What the return value (output) will be
• Any exceptions that can be thrown explicitly and why

These can become useful reference tools when you are trying to debug code. Many IDEs will also use the API docs in their tool tips as you hover over the function name.

If it's a language without those features, the comments help, but not nearly as much.

-
Is it acceptable if the output description is included with the summary? For example, `Returns the square root of X` also describes what the return value is. – Maxpm Dec 6 '10 at 18:40
Yes; what students should be taught is to use these documentation features. – Jeremy Dec 6 '10 at 18:47
I like to keep the API docs more at a logical abstraction if possible. For example, `Returns the color for this ray` or `Returns the requested Message, or null if it can't be found`. But yes, the summary is the meat of the API docs. – Berin Loritsch Dec 6 '10 at 19:26

If it's a public API method then yes you should provide detailed documentation, especially on parameters and expected behaviour. Many people feel that this can be relaxed for private methods/functions, YMMV.

Overall I prefer writing clean code (small methods/functions that do one thing and one thing well) with sensible variable names. This makes much of your code self-documenting. However, I certainly always document any edge cases, uses of concurrency and complex algorithms.

In short think of your self as a little bit worse for wear at 3am in the morning 3 months from now. You'll be thanking yourself for your awesome public docs as opposed to figuring out what parameter (boolean flag) means...

-
Sometimes functions may have corner-case behavior which differs from what the algorithm would imply. For example, rounding a `float` to an integer by adding 0.5 and taking the floor of the result will cause the largest `float` below 0.5 to be erroneously rounded up. In such cases, it may sometimes be important to distinguish whether a function should be defined as rounding to the nearest integer (or the next higher integer when two possible values are equidistant), or as adding 0.5 (possibly with an intermediate rounding step) and taking the floor of the result. – supercat Feb 2 '14 at 21:00

That's similar to how most -Doc frameworks parse in-code documentation (JavaDoc, PHPDoc, etc.).

From Java, auto-generated by IDE:

``````/**
* [Description]
* @param str [Description]
* @param isCondition [Description]
* @return [Description]
*/
public int testFunction(String str, boolean isCondition) {
...
}
``````

This is the same format used to generate the Documentation for the built-in language features - Example: http://download.oracle.com/javase/6/docs/api/java/lang/String.html

This format is quite helpful because it clearly shows to any third-party user how to interface with your code. If your functions are private methods that are only used internally, then it can be a little pointless - but I'd guess your teacher is trying to get you into a good practice until you are all experienced with making that distinction.

The only bit I often find somewhat redundant is the return description - Usually it's nearly identical to my method description.

-

There's two purposes for Comments:

1. They serve to remind you quickly what your code does when you come back to it months/years later. This way you don't have to re-read and analyze your code to refresh your memory.
2. They relay to other people who may be reading or working with your code what your code is doing.

There's of course many MANY different ways to approach this but the more thorough and consistent you are the better. Effective commenting takes time to learn just as effective programming does. Keep in mind that its hard to see the point of comments in school as nothing you're working on is ever large enough to really warrant it but they're just trying to introduce it to you. And usually the way the teach you to do it is your professor's style not any sort of standard by any means. Develop what works for you. And remember... there is such a thing as a stupid comment! :) Example:

``````a += 1; //adds 1 to the value in a
``````

Really? Thanks! LOL

-

I like the documentation from PHP website so I use something similar for my inline comments, and using PHPDoc syntax. See the example below.

``````/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int \$id ( The id of the client for which you're requesting access. )
* @param object \$db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( \$id [, \$db] )
*/
function allowed_locations(\$id, \$db=NULL){ ... }
``````

And like @Larry Coleman said, inline comments should tell why you did some piece of code.

``````\$funcResult = SomeFunction();
if(is_array(\$funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
\$c = count(\$funcResult);
} else {
\$c = 0;
}
if(\$c == 1)
{
...
}else
{
...
}
``````
-

If it's in the service of Doc generation then verbose comments (although irritating) are probably a good thing. Although you have to make it a team goal to stay on top of comments and keep them up to date.

If it's just the commenting style I would have issue with it. Excessive comments can hurt code just as much as help. I can't count the number of time I've come across comments in the code that were out of date and as a result misleading. I usually ignore comments now and focus on reading the code and the tests of the code to understand what it does and what is the intent.

I would rather have clear concise un-commented code. Give me some tests with descriptive assertions or methods and I'm happy and informed.

-