Commenting/In-Code Documentation Styles

Question

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?

Answer 1

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 else¹ 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.}

Answer 2

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.

Answer 3

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

Answer 4

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.

Answer 5

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

Answer 6

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
{
 ...
}

Answer 7

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.