Please stop commenting your code

Code is the easy part to understand. Instead, spend your time giving me the broad clues as to how the code base hangs together: the concepts, the intentions, the analogies, your thinking, how you see it being used.  And then tell me the gotchas.  

How about only writing code comments when there's something newsworthy to say?  Or giving me an example, or pointing me at a test if tests are rare?  What if we accept that our project and team has conventions, and we kind of get them, so you don't need to cover them off in comments? There would be fewer comments, and those that survive would be more likely to be useful.  

The alternative is a nice formatted file with standard or bland comments that will just fade out as background noise—noise which is often (a) pointless and (b) out of date.  And possibly the worst of all this, comments that are just taking up space on my screen, and masking actual useful information that might possibly be buried under some "returns a list of users from the database"-style worthless comment. 

I'm not saying no to comment.  What do you think of this: 

For instance, would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments? In most cases, code's readability suffers more when it's overly verbose than when it has a high comment to code ratio. Thus, I would choose to write the comment in most cases.

via jasonmbaker.com

Only a year ago I had the opposite opinion, but now I'm in total agreement. Plus, if you find a funky or idiomatic one-liner the comment would pass that technique on to the team. But please only do that once: don't copy and paste the comment with the code.

Yes, I've joined the anti-comment bandwagon.  

Comments:

makeurownrules said...

Hi Richard, I totally agree with you that the comments in the source code should be more meaningful and less verbose. I always find unit test cases more meaningful than the comments in the code and most of the times comments in the actual code is outdated and confuses developers. I would say debug log statements are better substitute for the comments in the code.

So code should only have comments if there is complex business logic.

Cheers,
Kapil
www.makeurownrules.com

tumstech said...

This is actually food for thoughts..! some thing to think about. i have seen code where there will be two functions / methods that do some similar operation, lets say like one function to execute and other to validate and other to display, all three functions will have same signatures, so they cut copy paste the code, and i see the comments remain same for all three (even the function name in the comments for all three).

I have omitted reading comments unless needed. I use IDE such as Eclipse, which help me in folding the comments and so i never get annoyed because of 10 lines of comments that makes no sense to me. and i still get to see only code in my window.

There should be a good practice of writing code in which we need to write comments only when required, just as "kapil" mentioned already.

FOR JOKE: We need to have a compiler which along with compiling should validate the number of lines of comments, and through some logic should throw a warning, saying, there is so many comments than code lines. ;)

Richard Dallaway said...

Thanks for the feedback ...

@makeurownrules - "source code should be more meaningful and less verbose" yes, but I think my emphasis is on making them more helpful, erring towards a default position of "add no comments until you need them". In fact, I'd rather people start with a README (or similar) for the overview. It's that high-level overview I think is most lacking... giving me a clue as to get my head around what approach has been taken.

I think this is all very team specific and language specific. If you have a language that encourages you to pass parameters in arrays (an example from a comment on dzone), you're kind of screwed and need to document what each parameter means.

Also, if you're writing a public API, the rules are quite different.

@tumstech the copy and paste thing, and the need to hide comments to see the code is annoying. I hate to think of the amount of time taken writing them (probably very little) compared to the amount of time taking reading/ignoring them (many times greater, I suspect, but I've not done a survey to find out).

I wonder if tools like checkstyle can be configured to reject code with duplicate comments ;-)