0

This is something that has bothering me for a while now. I guess there are a couple of obvious important things that should go into a comment, such as:

  • The author(s)
  • A description of the parameters (and their types, if we are in a dynamic language)
  • A short description of what the method does, e.g. "Trims leading and trailing white-spaces for unlimited length strings."
  • If it throws exceptions.
  • Semantics of the return value.

But one could image all kinds of information that could be added to such a comment, for instance:

  • Usage examples
  • Explanation of how the method is used in the project scope
  • TODOs / Nice to haves for this method which are not yet implemented
  • And probably many more

Now my question is, how do you write a really good method or class comment (that is, what information do you put in it, and how do you make sure it is kept up-to-date), with just the right amount of information so that any developer who has to work with your code is up to the task, but considering the fact that as you add more and more information to your comment, the probability for it to become outdated rises (e.g. if I add pointers to where the method is / will be used in the project, it could be replaced in that location or it might very well never be used, even though it was intended to).

Improve this question
1

6 Answers 6

Reset to default
9

It's probably instructive that, of the 99 Gotchas in Stephen Dewhurst's C++ Gotchas, Gotcha #1 is Excessive Commenting:

Comments are not inherently harmful — and are often necessary — but they must be maintained, and they're typically harder to maintain than the code they document. Comments should not state the obvious or provide information better maintained elsewhere. The goal is not to eliminate comments at any cost but to employ the minimal volume of comments that permits the code to be readily understood and maintained.

Improve this answer
7

Reading what it does (which you described) is useful - but what's even more useful is why it is required and how it fits in to the bigger scheme of things.

Improve this answer
5

The author is utterly useless information to put into a comment. No end user will ever care about that, and if a tech lead needs to find out who wrote something, he can use the revision control system (you are using a revision control system, right?).

Todos are OK only if they are for your use and you remove them when you are finished/before you commit to the repository. Otherwise they're tiny ticking time bombs, ready to explode in the face of the next person who maintains that code and create additional work and distractions. And you just know it's going to be the time when they have 5 minutes to fix some critical production bug.

Describing the method/class, arguments, return value, and (sometimes) exceptions are useful, mainly because they can be used to populate code completion and/or code insight features (e.g. IntelliSense, Code Assist, etc.) In fact, when I use a 3rd-party API which doesn't have these, I always feel like I'm stumbling around in the dark. It's annoying to keep having to context-switch between the code editor and the manual - assuming there is a manual. The important thing about these particular comments is that they become metadata, which is not the case for any of the other things you mention.

Please do create documentation with usage examples, detailed explanations, assumptions, limitations, references to specification/requirements documents, performance characteristics, and so on. But please keep those out of the comments. That's not where they belong. Maintainers need to be able to read the code, and they can't do it efficiently if every 1 line of code is accompanied by 20 lines of comments. Javadoc/XMLdoc tends to balloon the comment:code ratio to almost 50/50 sometimes; that's already very high, and any more than that is going to be intolerable.

Improve this answer
3

What I hate most about a lot of the source code I have seen over the years are comments, especially the verbose ones that prevent you from reading the code. As far as I am concerned there should be only two reasons to have comments in source code:

  1. The comment explains something that is not visible from the code, and without the comment the code (or its effect) is hard to understand.
  2. The comments are used for automated documentation (and even that gets more in the way than anything else).

If you find yourself leaving comments all over the place because otherwise your code would be hard to understand, then it's time to have a good long look at your code and maybe read this book.

Improve this answer
2

I wish I could +2 Gnawme's answer because of this statement:

Comments should not state the obvious ...

The method of commenting that I've found to be most effective is this:

  • If the code isn't trivial, I first write out what I want it to do in comments as pseudo-code. As I fill in the actual code, I update the comments to reflect what I've written.

In the end, the comments don't necessarily tell you what the code does, but rather they tell you what the goal of the code is, and what I was thinking as I wrote it.

But something very important that's hidden in Gnawme's quote is the principle that your code should be self-documenting. It's FAR better to give your functions and variables descriptive names, rather than to try to subsidize poor names with explanatory comments.

The point is to minimize the amount of knowledge the developer has to keep in their head at any given time in order to be effective. Sometimes, that may mean that you have kind-of long function names, but who cares? A longer function name is better if it eliminates the need to jump to the definition (or metadata) to view its description. (Unless you don't have some sort of auto-complete.)

I've found that by giving descriptive names to functions, parameters, etc, it often eliminates the need to comment on what the function does and what the parameters should be. By using good naming conventions, you only have to comment on those for the odd-ball cases.

Lastly, please never use comments to disable code permanently! If there's a section of code that you're removing from usage, delete it. If you ever need it back, get it from your source control system. Use your source control system for the things that it's really good at - like seeing who wrote that line of code, when it was written, and what got add/removed in a revision.

Improve this answer
1

The best comment is the one you don't write.
Comments get out of date quickly.
I used to write pages of comments but now I use the following principles:

  • Fully name classes, method and variables with real words and not abbreviations or letters.

  • Use a source control system (my favorite is git) to store the user name, date of change, etc.

  • If you do comment, don't state the obvious in a comment. /* a new comment */

  • If the code isn't clear erough as is, consider writing more verbose tests to express the functionality rather than adding comments.

Improve this answer

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