Speaking about books, I recently finished to read the great book from Robert C. Martin, Clean Code. One really interesting chapter, is about comments and how they could be dangerous.
I will not speak here about javadoc and API documentation, but all other comments which are used to add tasks (TODO, FIXME), explain an hack or anything else.
The main difficulty is to keep them in sync with the code. As they are not linked to the code they refer, they may move with code addition/refactoring or become inaccurate if the implementation change. Another leak from these comments is that it is difficult to retrieve the author, or to start a discussion from one of them.
In fact, as this kind of comments are meta-data, it could be more logical to dissociate them from code, I mean to store them outside of the code.
We do it of issue tracking (and sometime for tasks), but then comes the problem of integration between tools.
In the last version of OpenOffice, notes are displayed in the margin. I find it very usable.
So here is a quick mockup, of what I would like to have for this kind of comments.
