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.
Very cool idea. The tricky part is going to be how to version-control the associated metadata and keep it in sync with the actual code. (It can be hard enough getting folks to check in all associated source code for a change ;)
ReplyDeleteFor Java, we can use annotations to add metadata to declarations, and refactoring tools could pull these along... A smart editor could display the annotations as you suggest. However, this would only work on declarations (you cannot attach annotations to any old statement)
Right click on your editor, team->show annotations and you get something really similar from a UI perspective.
ReplyDeleteI think pretty much everything is ready in Eclipse to do just that.
Moreover, your mockup makes me think such a tooling could greatly ease peer code review.
You should check out the TagSEA feature. It was a set of plugins that allows users to insert specialized comments in code, and add other annotations to resources in the workspace. The annotations are organized by "tags" which are used for finding them again later. As this was a research prototype, it has lost on development in the past year or so, but it is something that starts to implement what you are looking for: http://tagsea.sf.net
ReplyDelete