Should I use comments in code, liberally?

Question

All,

To comment liberally or not to?? Pros and Cons. I personally prefer commenting as it leaves nothing to the fancies of the people reading it.

Thanks

Answer 1

So long as your comments are useful and not (a) inaccurate or (b) hard to read, then yes, comments are good.

Comments that are inaccurate can be worse than no comments at all.

Comments that are hard to read will simply end up being ignored and make it harder to get through the code.

Answer 2

Jeff Atwood: Coding Without Comments

Answer 3

If your code genuinely requires liberal comments to be understood, then that's a definite code smell. Generally speaking I strive to write code that doesn't need to be commented.

Answer 4

I have a bathtub curve in comments:

Ordered by time:

1. Pseudocode in comments what I'm doing
2. Code the above, commenting confusing things
3. After code has reached stasis, I go back and comment the things that have begun to confuse me
4. I comment heavily in headers regarding how the code works, so when I come back to it, I can follow my thought.

Answer 5

In my experience commenting code when you write doesn't make sense, because you're likely to state the obvious. If you have to revisit the code then you know what isn't clear. Comment on that then.

Answer 6

You should use comments to descibe WHAT your code does, but your code should speak for itself regarding HOW it does it.

Answer 7

I think that's dependent the code your writing.

Here's my personal method of deciding how to comment things:

Things I comment:

• Overall class documentation

• Public facing robust methods that take a lot of options, and make assumptions are good candidates for strong comments.

• Internal methods that only do one thing should still be commented, but in a manner that they aren't included in comment based documentation generators.

• Cryptic methods should definitely be documented

• Internal statements, only if I did something really, really clever and know I'll spend some time figuring out what I did in the future.

• Block endings if the block starts off the page, with the block type and condition if applicable.

Things I don't comment:

• Methods with a clear name and list of arguments can probably get away with out it.

• Any line of code that hasn't already been covered.

Regardless of how you comment, there's such a thing as bad comments. Ensure the wording in your comments is clear, concise and relevant.

Answer 8

I try to comment only when necessary, but ALWAYS when necessary. Everyone has personal rules about when they do it and some companies have style guides to make you do it!

Of course, every professor in a CS curriculum will tell you to comment liberally everywhere mostly because programmers typically comment less than they should. I just hate to have "comment bugs" in my code which tend to confuse me worse than an actual bug in the code.

Of course, it also depends on what you're writing. If its a common use library for your whole company, I would tend to comment more. If its a one-off consulting-ware script, no comments is probably okay.

Answer 9

Possibly from O'Reilly's 97 Things Every Programmer Should Know (see also Guy Steele interview in Coders at Work).

Comment Only What the Code Cannot Say

Answer 10

Comments are usually good, but there are some things to consider.

First, they do take space on the screen, and in extreme cases can make the code hard to follow. Don't write comments unless they're useful. In particular, don't duplicate the code in comments. Favor in-line comments, since they don't take up vertical screen space.

Second, comments should not be a substitute for well-written code. Assuming you're working in a language where you can have long identifiers, showing the purpose of a class or function in the name is generally better than using a comment. (On the other hand, if the code is going to be difficult to understand no matter what, perhaps implementing a non-obvious algorithm, write the comments.)

Third, comments are only valuable if they can be relied on to be accurate. In general, developers will be lax about updating comments along with the code, so the safest thing is to not tie the comments to the code. Write comments to explain what is being done, not (unless the algorithm is of interest) how it's done. Comment what variables are supposed to represent, not how they represent it.

In general, remember that all the answers are in the code. Don't try to make it possible to get by without reading the code, since it has to be read anyway to figure out what's actually going on. Do write comments to make it easier to read the code.

Answer 11

I'm in the "prefer self-documenting code over comments" camp. I try and make sure that any comment I leave in code for others to see adds value that could not otherwise be expressed by the code itself.

While there are certainly exceptions, I've found that in general I write more comments the less I understand what I'm doing, which is typically a good indicator for me that I need to stop, take a step back, and rethink my design or approach. In that sense those comments are extremely helpful, although usually once I've taken the time to get a better handle the problem at hand I will have refactored the code such that the comments are unnecessary.

Answer 12

One caveat to the good comments about avoiding over-commenting code: Consider your "audience" as well. I've worked on internal tools used/maintained more by server admins than by full-time programmers, so more comments can be appropriate in that case. I would think the same could be helpful in cases when multiple languages are being used and not everyone is equally familiar with every language.

Answer 13

My rules:

• comment not trivial parts of code. Always describe WHY you do what you comment and not WHAT, which should be clear from code itself.
• highlight steps - it makes code easy to read

Answer 14

The easier your code is to understand (with liberal use of comments written in plain English), the easier it is for for other programmers to understand you work if you get hit by a beer truck. Your employer will like that too. :-)

Also keep in mind that too many comments isn't a major issue, as they can always be removed later. (but available through your revision control system. You're using revision control, right?) Whereas if there aren't enough comments, that knowledge can potentially be "lost" (such as if you leave the company, forget why you wrote a specific piece of code that way, etc.)

Answer 15

In my experience the people who think their code is self commenting are invariably wrong. Maybe you will remember why you did something a certain way when you revisit the code, but somebody else who has to maintain it will not.

If you have to do some research to write a piece of code then include a reference, or a note.

If you have to change a routine because of something you learned after the first draft then add information about your experience so somebody doesn't later change it back

Code reviews would be of immense help here, if your code is not self explanatory you would find out at the time, and save a maintenance programmer some lost hair

Answer 16

Often I find code that is desperate need of comments is also in desperate need of functional decomposition. Good short descriptive functions with good names are often better then some comment that hasn't been edited in ten years. I say this with the caveat that there are things you should defiantly comment. Magic code, nonstandard code and, very obscure logic or business rule should allays be commented.

however this is on of my pet peeves.

//Copies a record 
//This function will copy the Src Record to the Dest Record 
void CopyRecord(Record *Dest,const Record *Src);

In this case there is no useful information in the comment just a English version of what ever qualified c developer would know a use full information would be

//
//This function will perform a shallow copy from the src record to the dest record 
//Dest pointer  must be null and allocation will occur inside function 
void CopyRecord(Record *Dest,const Record *Src);

In this you were told how to use the function not what it obviously did.