The Old Joel on Software Forum: Part 4 (of 5)

Comments / code ratio?

Wondering if anyone bothered to measure this, and what people think are reasonable numbers. My ratio is around one comment per 6.5 LOC (wrapped to 80 columns, empty lines excluded).

arrayref
Tuesday, March 30, 2004

My ratio is 1:1 LOC:Comments

Pragmattic Programmer
Tuesday, March 30, 2004

I have a comment above every function that looks like :

/**
* This function removes the entry with ID entryId
* from the category with ID catId.
*
* If the currently logged in user does not have permission
* to delete this entry false is returned.
*
* If the entry does not exist a fatal error is set and false is
* returned.
*
* If either argument is blank or not a number a fatal
* error is set and false is returned.
*
*/
function removeEntry($entryId, $catId){

I would say only 1 in 4 of my functions contains comments within the function, when I am doing something that's purpose wouldn't be obvious from the function comment.

I really don't think there is anyway to get around that fact that reading code is hard work, comments often introduce uncertainties as their working can be vauge and misleading.

It am sure a lot of the bitching that programmers do is related to the fact that reading another person's code is harder than writing your own, I think it was Joel who said that.

braid_ged
Tuesday, March 30, 2004

I hope that 1:1 comment (no pun intended...) was a joke :)

I'd be suspicious of metrics that say you should have x number of comments per LOC.

Comments should clarify the intent of the code. As it says in Code Complete (I think), if you find yourself putting comments that explain what your code does, as opposed to why it does it, you need to write more readable code, rather than trying to fix up unreadable code with comments.

(I guess that was a digression, but the point being that some code requires more explaining than other code, so metrics are dubious.)

Mike Treit
Tuesday, March 30, 2004

braid_ged, I think your example is unnecessarily wordy. Why start with "This function...", what else it can be? ;)

Mike, it's often difficult to draw the line between the "what" and "why" here. I find it A LOT easier to comprehend code with a comment at start every chunk, even these fairly obvious and code is my own. By chunk I mean several related statements, delimited by an empty line. Althought I might be a litte biased since I code in Perl, whose statements are usually more dense than, say, Java.

arrayref
Tuesday, March 30, 2004

MZ Tools has a statistics function... that counts LOC and comment lines. On the project I checked had ~ 15% LOC - 11,165 Total Lines, of which 1670 are comments

Wunderkind
Tuesday, March 30, 2004

As so often, as few as possible, no less. More comments == more likely to get out of sync!

_
Tuesday, March 30, 2004

#comments / #lines ~= 0.1.
#comment-lines / #lines ~= 0.3.

A lot of my comments are fairly long ones documenting classes and methods. Some of them are for Doxygen to read, which means they're a little more verbose than they otherwise would be.

Gareth McCaughan
Tuesday, March 30, 2004

9500 lines of code; 1900 lines of comment, of which 231 are mixed code/comment lines.

Mr Jack
Tuesday, March 30, 2004

arrayref,

<quote>
Wondering if anyone bothered to measure this, and what people think are reasonable numbers.
</quote>

Steve McConnell is excellent on this topic. Read http://www.stevemcconnell.com/cc2/32-Documentation.pdf (it won't be available online for much longer).

Seeya

Tuesday, March 30, 2004

someone mentioned MZ-Tools. this is what i get here:

Code Lines: 113'937 (80%)
Comment Lines: 26'938 (19%)
Total Lines: 140'875
Procedures: 7'570
Controls: 2'099

cheers,
</wqw>

wqw
Tuesday, March 30, 2004

// Delete a file
//
// Asshat boss decided to count comments, so I'm putting
// a few in. This function takes a file, and deletes it.
//
// In fact, as we're on a modern file system it pretty much
// shreds it.
//
// Better not want to recover it, cuz it's gone for good.
//
// Wonder if that cute chick in Marketing will go out with me?
//
// There, that should do it.
void deleteFile(char *name) {unlink(name); return;}

Snotnose
Tuesday, March 30, 2004

Had it not been O-Dark hundred my brain would have kicked in and my line would have been:

int deleteFile(char *c){unlink(c);return(0);}

;)

Guess what my opinion of automated tools for this kinda thing is?

Snotnose
Tuesday, March 30, 2004

Big comments are like big hair: serves no useful purpose and just gets in the way.

skinhead
Tuesday, March 30, 2004

Your boss really is an asshat. LMAO.

skinhead
Tuesday, March 30, 2004

Never thought about that stat. Some quick greps and wc -l seems to give my code a ratio of around 1 : 4.

As for my commenting methodology, the majority of my comments are of the form of API docs. i.e. what will this class/method do for me as the client of the code. If the method is obvious (eg. most setter's getter's) they don't get comments.

I find that when I am looking through code (others or mine from the past), it is much easier to understand if I know what a given method/class is trying to accomplish before I dive into the code. To me, this seems to argue that comments should say "What" and not "How", with the exception that if the How is non obvious, inline comments are ok. However, I have seen it said in this thread and elsewhere that comments shouldn't say "What" but rather "Why". What is the argument against "What"? I find that much of the time the "Why" is obvious from the "What". When it isn't, the "Why" needs to be added as well.

And what about the "Who", "When", and "Where"?

madking
Tuesday, March 30, 2004

A question for the peanut gall: do you find that there is a consistent relationship between the size of a comment and the size of the block of code to which it refers?

Danil
Tuesday, March 30, 2004

Re: peanut gallery, my comments depend more on conceptual density than size. In Java, some things are artificially verbose, some things aren't. It's like that lesson they teach in school: one sentence per concept. For all the good things about Java, it doesn't have that ratio.

Tayssir John Gabbour
Tuesday, March 30, 2004

My comment ratio is more "it depends". Most of my comments are in the .h file. About the only time I comment the source is when I'm making a note to myself, or doing something non-obvious.

Of course, the classic comment was in the original Unix code, /* you aren't expected to understand this */ followed by some odd assembly code.

Another issue is who will maintain the code. I just finished spending 3 days on a fairly complex Makefile. As I don't expect to be around much longer I commented that puppy pretty heavily, my ratio is 50/50 or better.

Snotnose
Tuesday, March 30, 2004

About 10% here

Joe Hendricks
Tuesday, March 30, 2004

WTH is an asshat? It sounds like a hole that you put your head in, but I really don't want to think any further than that.

Wednesday, March 31, 2004

Eric Lippert wrote about this last month:

http://blogs.msdn.com/ericlippert/archive/2004/03/10/87384.aspx

MacSqueeb
Saturday, April 3, 2004

I use a semi-formal comment style. My function comments look like this:

/*
FunctionName
Purpose:
Explain what the function does.
Inputs:
Param1 - Explain how 'FunctionName' interprets Param1
...
ParamN - ...
Outputs:
OutParam1_n - Explain what goes in any out-params
Result - Explain the return value of the function
Assumes:
Explain any assumptions about environment state, parameter interrelationships, etc.
Modifies:
Explain how (if applicable) this function changes environment state (or object state).
Notes:
Explain how the function does its work. Diagrams and reference URLs go here.
*/

I don't specify each and every field for each and every function. For example, a function to reduce escape sequences (\" \n ...) in a string has a brief statement of purpose and a brief mention of its input and output (with a list of valid sequences under the 'assumes' section). The 'UpdateWeight' method of a weighted binary tree class, on the other hand, has a brief statement of purpose, inputs and outputs, and a lot of little diagrams to explain what happens in various edge cases and why the tree's state is changed in the way that it is.

K
Sunday, April 4, 2004