While there is considerable conversation about how many unit tests to write (I have two recent posts on the topic--here and here--based on conversations with vendors), few people have much to say re how many comments there should be. Once the usual themes (more comments, keep comments up-to-date, avoid pointless comments) have been stated, the conversation ends. Everyone understands what relevant and up-to-date comments mean, but few will hazard a guess as to how many of them necessary.
Interestingly, the comment ratio is a key factor in one of the most interesting metrics, the maintainability index (MI). It is also a ratio that is rewarded by Ohloh.net, the emerging site for tracking details of open-source projects. Ohloh gives projects a kudo for a high percentage of comments. The question is how high is high enough to earn the kudo. According to Ohloh, the average open source project runs around 35% comments. Projects in the top third overall get the kudo. I don't know the cut-off for this top third, but I do know Apache's FOP with a 46% ratio of comments definitely qualifies.
Comment count is a metric that is particularly easy to spoof. You could do what some OSS projects do and list all the license terms at the top of each file. I've always disliked scrolling through this pointless legalese. In my file headers, I simply point to the URL of the license, which is sufficient. But all the license boilerplate inflates comment counts amazingly. So does commenting out code and leaving it in the codebase (gag!) or writing Javadoc for simple getters and setters (also gag).
But where legitimate comments are concerned, 35% is probably a good working number to shoot for. I find many OSS projects at this ratio have quite readable code. I'll be working to bring my own codebase up to this level.
There has been discussion of versions of the maintainability index that remove comments -- http://www.stsc.hill.af.mil/crosstalk/2001/08/liso.html.
ReplyDeletePersonally, I like this better given the noisy boilerplate commenting and javadoc comments that end up in code these days.
More importantly, in my opinion, comments are a fallback to be used when the code itself couldn't be made clearer. Writing a comment is usually a "crutch" along the lines of the famous correspondence, "Sorry this letter is so long, I didn't have time to make it shorter."
The code is executable which makes it the authoritative documentation and it should be clearly written which reveals its intention to those with an interest in understanding it. Therefore, well-written code will suffer under a quality metric based on comments.
Bob: Great link and one that takes a much more sophisticated view of comments than Ohloh's "more is better." In fact, as the article points out, a ration of more than 25%-30% comments should be penalized, not rewarded.
ReplyDeleteI agree with your larger point, although more often than I care to admit I have added comments to my code to clarify intent, when I probably should have renamed variables and reorganized the code.
I think we all reach those times where we have to drop back and punt to comments :-)
ReplyDelete"Once the usual themes (more comments, keep comments up-to-date, avoid pointless comments) have been stated, the conversation ends."
ReplyDeleteI usually try to take the converstation in the other direction by saying "comments are evil". It may not be entirely accurate but it does perk up the discussion. :)
In reality I agree with the comment guidelines from the first edition of Code Complete which said that comments should be used for things that are non-obvious or counter-intuitive, and there are cases that are just inherently that way (usually because it is a factor in a library/api that you are using and can't control).
The difficult question is in those cases where we "drop back and punt to comments" are we making a good optimization (not worth making the change to the code) or are we discounting the future (I'd rather pay 5 units of pain tomorrow instead of 1 today).