When NOT to comment code

Question

What are your "favourite" overuses / misconceptions about commenting the code? Why do you sometimes think commenting is a pain? What arguments would you use to convince others that less is more at commenting in some cases?

This is the negative counterpart to How to convince people to comment their code - such that it remains a collection of answers, not a convoluted discussion. Compare also Commenting code, Do you comment your code, and What's the least useful comment you've ever seen?

How about writing one reason per answer, so the voting works on the reasons?

Answer 1

Writing good comments is an art just like writing good code. When too many comments obfuscate the code itself or when the comments duplicate the code then it may be time to back off a little.

Answer 2

The classic way NOT to comment is:

//add 1 to count

count++;

Rename count to tell me what you are counting and I don't need a comment. Telling me what the counter is used for would be okay in a comment.

Answer 3

Some conventions require you to enter tons of nearly useless javadoc-tags. For instance:

/** The ID for the User. (For the format compare {@link IDGenerator}). */
private String id;

/**
 * Gets the ID for the User. (For the format compare {@link IDGenerator}).
 * @return the ID
 */
 public String getID() { return id; }

/**
 * Sets the ID of the Object. (For the format compare {@link IDGenerator}).
 * @param id the ID to set
 */
public void setId(String theId) { id = theId; }

EDIT: My point is especially that in some conventions you are enforced to comment the variable, the setter and the getter, although they are nearly identical and should be unified. This might be good practice for public APIs and Open Source Code, but is certainly overdone for internal code. For this purpose I'd suggest to leave out the @param and @return tags and just comment the getter.

Answer 4

Comments are sometimes used as an excuse for writing obtuse code.

By encouraging others to write less comments, it sometimes encourages them to use better names in variables, methods, etc. and use more understandable logic and flow.

Answer 5

// gets the user from the session
User user = session.getAttribute("USER");
// Gets the comment from the user's comments from the comment id on the request
Comment comment = user.getComment(request.getAttribute("COMMENT_ID"));
// Adds one to comment rating
comment.rating++

Answer 6

Don't explain the programming language to the reader. You should assume readers know the language as well as you do (or can look things up if necessary).

For example, I once saw C++ code that looked something like this:

// This is a template.  A template allows us to specify a
// class that can be parameterized with other types.
template <class T>
class Foo {
   // ...
};

// Use 'typedef' to declare type aliases
typedef Foo<int> IntFoo;     // IntFoo instantiates Foo for 'int'
typedef Foo<char> CharFoo;   // CharFoo instantiates Foo for 'char'

Such comments make sense in a tutorial, but they don't belong in production code.

Answer 7

I'm not advocating no comments, but IMO, code should be self descriptive. If you function/method is doing more than one thing than the name implies, refactor.

Answer 8

If your variable, property, and/or methods are named correctly and the code you are writing is not complex you won't really need to comment.

For example:

public bool isStackEmpty()
{
    return (this.currentStackSize <= 0);
}

Answer 9

Sadly, when commenting is required for the sake of requirements, you get a bunch of "English" versions of the syntax.

The classic

// Add one
i++;

I've been required to generate 50% comments by a contract and ended up generating garbage like that. Even worse, it became part of my normal coding style. DON'T DO AS TIMMY DOES.

So my reason not to comment "Don't comment just because someone thinks there should be x% comments". That is just stupid.

Answer 10

Worse case I've seen is:

// Adding an extra comment to push my percentage of
// comments over the amount required
i++;

Serious horror!

Answer 11

What’s the golden code/comment ratio?

Answer 12

I think a goal of every developer is to over time be able to write commentless code. Code that self expresses itself is beautiful code. I wouldnt go so far as to say its an excuse to write bad code, but a lot of people dont have enough experience or ability to write code that requires little or no commenting. It takes a long time, a lot of practice and experience.

Bottom line, as you get older and grow fatter, your comments should get thinner ;)

EDIT: In case others wish to downvote me for whatever reason, just to make it clear this is in general and does not go into detail about commenting complicated intentions, etc. If you disagree, put a comment so i at least know what your disagreement is. How the hell are we supposed to learn from each other with silence.

EDIT2: just figured i would add a little extreme snippet

//This check makes sure the nuclear reactor is within normal parameters
if(a < 5 && b > 8 && c == 9)
{
    ...
    ...
}

This should be refactored for 3 reasons. Reduce commenting, increase readability, reuasability

if(IsNuclearReactorWithinNormalParams(a, b, c))
{
    ...
    ...
}

bool IsNuclearReactorWithinNormalParams(int coreTemp, int stackTemp, int reloopThreshold)
{
    return coreTemp < CORE_OVERHEAT_TEMP && stackTemp > STACK_MIN_TEMP && reloopThreshhol == RELOOP_THRESHHOLD;
}

Look ma, no comments!

But even still the incoming params should also have been refactored and renamed to proper names so it is clearer. When you follow stuff such as this your commenting becomes reduced by a huge factor. ESPECIALLY when it is a mission ciritical app. Comments alone just dont cut it in mission critical apps.

Answer 13

// fix for bug #6837
splines.reticulate();

Don't comment why you made a change. Put those comments in the source control system, so the comment is attached to the change itself.

Answer 14

Don't detail the history of how code got to be how it is. That's what version control is for.

For example, don't do this:

// This method was originally called GetSalesDollars(), but now that we
// support other currencies, we've changed the name.  :)
Money GetSales() {
   // ...
}

or this

// oops.  This crashed if the denominator was zero
//return sum / n;
if (n != 0)
    return sum / n;
else
    return 0;

You might think such comments will be helpful to future readers, but honestly, nobody cares. This stuff is just cruft that will build up and make it harder to read the code. Tell your war stories in a bar or on your blog, not in production code.

Answer 15

IMHO, if you have a block of code that is complicated enough to warrant a comment, an alternative to said comment is to throw that code into a function that has a descriptive name.

Answer 16

To me, comments are meant to explain why you did it that way not what you did. If you have to explain what you did then the code probably sucks and needs to be redone.

Answer 17

A great place to not comment code is when the code is self-commenting (i.e. variables are well named, program flow is clear, encapsulation has been used correctly, etc.).

However, as a caveat I would submit that knowing this about code you're currently working on is really hard for most people to do. This is because code that is currently being developed by you or those on your team is usually pretty obvious to yourself and your teammates. The time when comments really pay off is when a new developer either comes on to the team or has to begin to maintain a source tree that they have never worked on before. For instance, I recently began to look through the Wordpress source tree, and the fact that there are lots of segments of code that are uncommented or commented on by someone who clearly was very familiar with what the code did already has made it very difficult for me to get a grasp on the system right up front.

So, a 'best practice' might be the following (I don't actually do this, but I'm trying to get in the habit): When you write a new piece of functionality, get a fellow programmer in your team to come over, sit them down, and explain what your code does (or possibly better yet, try to have them explain what your code does) and, if that goes over without a hitch, you probably don't need a comment. If it is challenging, comment away, and long after you're no longer working on the project, that code should be clear to whoever has to work on it.

Another great benefit to this would be the following: Should you be unable to think of anything but an obfuscated way to implement a feature, if you clearly document your intention, someone who comes along later who might have a different flash of insight than you will be able to see what it's doing right off the bat and refactor it, knowing that they are still following the original intention of the code block.

That's my two cents at least.

Answer 18

Leave older versions of the code as comment is also quite a bad practice, too often seen.

Answer 19

I think that you MUST comment any block of code that has business logic or code that seems to be doing something that follows rules that are relevant to the flow of your system so it wouldn't make sense to add a comment to tell the developer that you are looping through a collection but maybe it makes sense to tell the developer WHY you have to loop through the collection or why you break if X happens.

Answer 20

Commenting that is overly verbose is generally not only unnecessary, its a bad idea. Your comments, if needed, should be just as clean as your code if not cleaner. I only truly expect large blocks of commenting when the functionality is commonly used and thus elicits many questions or the functionality isn't clear.

Also, if you're in Visual Studio, I highly recommend GhostDoc as it can eliminate a lot of typing on your part for simple things that need documentation.

Answer 21

You should not comment when self explanatory code is enough.

For instance:

// Verifies if the "credit" ( or whatever ) is approved.
if( tries < 15 && x > 0 && x <= 1 && y != x || count == d  ){
    ...
}

Sure it deserves a comment. But this is way much better

if( isCreditApproved() ) {
    ...
}

Remember:

Blockquote

Any fool can write code that a computer can understand. Good programmers write code that humans can understand. -Martin Fowler

Blockquote

And everyone knows that comments are not executed.

Answer 22

Don't leave commented-out code in source files.

If you don't need it, then you don't need it. Delete it. You can always get it again from your version-control system.

If you think you might need it, then instead of commenting it, enclose it in a conditional-compilation block, move it to a separate function, or otherwise get it out of the way and clearly mark it as not-real-code.

Answer 23

I use comments for three things:

1. Auto-Documentation: For use by IntelliSense systems, even if its 'obvious' by looking at the code. It infuriates me no end to see other libraries or apps that lack member documentation when I'm trying to browse them from IntelliSense, so I make sure to fill in all of mine.
2. Justification: The best use of a comment, saying why the code exists or is needed. This shouldn't consist of too much 'how' or 'what' though.
3. Summary: In larger methods or property lists, I title subsections or groups with a small comment to say what the section does for easier reading and parsing. As a side effect, if I find myself describing two methods with the same sub-section names, it helps suggest a possible location of duplication that I should refactor.

Answer 24

Code should always be as absolutely self-documenting as possible. If you look at a piece of code and realize you can restructure it so a comment is no longer necessary, that is the best course of action, since it makes the code easier to understand.

Obviously, this doesn't mean you should never used comments--it means that code should be designed so as to be as understandable as possible before people look at the comments. Comments should be reserved for FIXMEs, explanations for non-obvious tricks/hacks/similar, and explanation of complex algorithms and functions. The majority of code should not need significant commenting.

Answer 25

If a comment makes you feel stupid while reading it, you should really try to avoid committing that comment to your source control.

Example:

// I've no idea why, but this fixes Bug#0815:
i++;

---

If a comment makes you feel smart while reading it, you should really try to avoid committing that comment to your source control.

Example:

// This is the fastest strReplace *evarrr*!
// I got it from this nifty coding site:
// http://thedailywtf.com/Articles/My-str_replace()-Can-Beat-Up-Your-str_replace().aspx
function fixString($string, $chars = 0) {
    // ...

---

I have to admit that in both cases, the primary problem is not the comment. But they're a "smoking gun", so to say.

Answer 26

Almost all comments can be avoided using the Extract Method refactoring and giving a good name to the method.

I only comment code that can me misunderstood and removed by other programmer on the team, as an example, last week I had to comment a code when I used something like:

Field.Value <> Null

It would take, hum, let me think, 2 minutes until someone would change that to Field.IsNull, but the problem is that IsNull in a Aggregate Field, Always return True (if I'm not mistaken) in Delphi, so changing it to IsNull would introduce a bug.

But I extremely recommend you to think twice before writing any comments, comments are most likely needed when the code is bad.

Answer 27

I just love these:

//
// Set the DIB bits to the device.
//

result = SetDIBitsToDevice( ..10 arguments or so );

Answer 28

At worst, comments can lie. At best, they can be redundant.

They're usually only okay for something unintuitive. As in.

// HACK: If I don't call this twice, Foo breaks. 
Bar.Setup();  
Bar.Setup();

If you have a method like this

User.Save();
// Send confirmation email...

That's a code smell, and you should refactor to method.

User.Save();
sendConfirmationEmail();

Answer 29

Based on a true story. Don't ask a question in comments for some other hypothetical person to answer:

// Crap, why is this here?
// Well, just in case it happens somehow.
if (i < 0.0)
{
  printf("Uh oh!\n");
  i = 175;
}

It's better just explain why something is there in the first place, and if you're doubtful, make sure you resolve the problem yourself, find the answer, or ask someone (your colleagues, stackoverflow, etc.)

Answer 30

Saw this once in a class where we were told to "comment everything."

//This is pretty obvious
int num = 2;
//duh
char yesno = 'n';
//just declaring some more
char yesno2 = 'n';

...etc.

Answer 31

If you reasonably can figure it out from the code, don't comment it. If the code's so complicated you can't understand it, change the code if you possibly can, rather than clarify with comments. Don't use comments to give a quick description of what a variable or class or function is for: use the name for that.

Typically, around here, comments are used to explain decisions (why is base_rpm 1200?), explain nonobvious things in the code (avoids the problem in case 1234), describes usage, or to give a high level view (calculates frammistan clearance using Howard's method).

Answer 32

Don't comment the end of blocks. i.e.

if (...)
{
    ...
} // if

If your blocks are that big that you can't figure out where they start & stop, you seriously need to refactor your code.

Answer 33

Important is what you comment. Do you comment what the code is doing, or do you comment your intention why you code it this way?

For me are comments that describes what the code is doing pretty useless. I can read the code by my self, but i can't read the mind of the other progammer.

Answer 34

Whenever human possible, write code that doesn't need comments:

When you feel the need to write a comment, first try to refactor the code so that any comment becomes superflouus.

-Martin Fowler ("Refactoring: Improving the Design of Existing Code")

I think commenting code is a bad habit. Commenting code should remain something rare and exceptional.

The time is better spent with:

• document your code (public methods, purpose of classes, runtime behaviour, configuration)
• document your design decisions
• let others review your code
• automatic testing

Answer 35

Don't use comments in lines like

//if red is true then
if(isRed())

Answer 36

I just hate comments created by GhostDoc. As if

/// <param name="participant">The participant.</param>

Wasn't already obvious. And cleaning / enhancing that just to create a nice, documented framework is really tiring.

Currently I prefer using #regions rather than comments because they kind of wrap code so that you know without looking at identation when it has ended.

Answer 37

sorry rshimoda, I repectfully disagree. I use GhostDoc to ensure my methods/properties etc are correctly named. If GD does not automaticaly give me a comprehensive and clear comment then I need to rethink my method name. I agree the parameters are somtimes a bit obvious but its better than writing the whole thing yourself. After using GD my method names have become much more user friendly. this may be more of an idication of my coding than GD however.

Answer 38

A summary of my "favourites" (some mentioned above) would be:

1) Comment the intent of the code, don't restate what the code is already stating

2) Don't leave commented out code lying around - delete it. (That's what source control is for)

3) Don't have massive blocks of comments at the top of a class/module stating the history of changes to the code - they never maintained and therefore are completely out of date within one or two edits aside from being completely useless. (Again...source control)

Answer 39

I forget why I read it, so I'm probably going to misquote here, but:

Code tells you how, comments tell you why

Answer 40

I don't comment when code is intuitive/informative enough to show what is going on.

Answer 41

When coding a submission to the IOCCC.

Answer 42

When not to comment code? Always! Let your code be self-documented!

Answer 43

The basic method to decide, to comment or not to comment the code is to look at the section (of the code), as if you were reader, and listen to yourself. If your internal voice want's to ask: "what the hell is this?!" - then you obviously need to place an explanation on the thing, that confused you so much, otherwise it's all depends on - what do you think, the reader (which is not you) will be able to get it right, or not. Also, I would quote someone of answerers with a little addition:

Code tells you how, comments tell you what and why

Answer 44

Many IDEs generate useless comments (especially Javadoc style comments). As an example here's what you get with a lot of them when generating getters and setters automatically:

int foo;

/**
 * Returns the value of foo
 */
int getFoo(){
  return foo;
}

/**
 * Sets the value of foo
 */
void setFoo(int foo) {
  this.foo = foo;
}

Answer 45

If you have to explain it during a peer code review, it probably deserves a comment.

Answer 46

I'd say don't comment code that is highly complex. The comment will leave future developers more confused about the behavior of the code. It is infinitely better to write unit test cases for such complex methods. Properly documented Unit Tests are much better than code comments.

Answer 47

I once took over code with a lot of comments similar to the following in it:

function XYZ()  
{
... Lots of really bad code ...


/** f### the <some Client Name> again changed his mind, 
it is the third time this week I had to change this code, 
I am really getting <some more swearing > with this, what is it with him.  
Now I had to change this back to how I originally had it, , <some date> . **/

/**
Some code.
**/
... Some more really bad code all in one majorly long function ...  
}

Answer 48

In addition to the already-mentioned pointlessly trivial comments, there's an unpleasant habit here of putting ASCII 'borders' around them, wasting two additional lines.

//===========================================
// Log off from the system.
//===========================================
system.LogOff();

There is also a tendancy to use giant comment 'banners' to split code up into categories, like so:

//===========================================
//===========================================
//
// PRIVATE FUNCTION DECLARATIONS
//
//===========================================
//===========================================
int some_function();

Quite often I find myself playing a tedious game of 'spot the code.' One time I came across a perl file with 200 commented lines and 10 lines of code! This kind of thing really put me off comments, and I barely ever write any of my own now, preferring well-named short methods instead. (I've also set the comment highlight colour to the lightest shade of grey that I can just about read, which keeps the noise down quite well.)

So I guess my recommendation is if you really must comment, don't 'decorate' them and waste even more valuable screen estate!

Answer 49

I saw this the other day:

If x = y Then DoSomething   ' one line if

Thanks for the clarification!

Answer 50

Straight from Suns official Swing documentation (on tree widget nodes):

/**
 * Returns true if the receiver allows children.
 */
boolean getAllowsChildren();

Allows children to.. what exactly? Can I add nodes by drag&drop? Should the ui display a handle to open this node? May I still add children later when I said no?

Any half decent perl script could have made a better comment.

Answer 51

Comments can lie. Unit tests cannot. Use good variable/method names and write unit tests: then I'm happy.

Answer 52

Perhaps part of the reason people find themselves adding comments is that they are being taught to do so. Teachers frequently require comments almost everywhere. It would be nice if teachers instead taught about intelligent naming of functions and the like, but this is insufficient because the normal strategy of knowing what a function does because it is well-written does not apply if code is poorly written.

It would make for an interesting assignment to give a student very well-written, working code and ask them to get rid of every comment yet make the code just as readable. However, classes tend to focus on theory rather than practice far too often, and it is more work to grade such assignments.

Answer 53

When the comment can be removed by correct programming:

Bad code/comment:

// Remember to put a slash at the end
directory = "/usr/rush/data/";

Good code:

if (directory.last() != '/') {
    directory += '/';
}

Answer 54

1. Don't comment the obvious
2. If you didn't comment and it wasn't so obvious after all, add a comment

If some code doesn't seem to make sense, you "fixed" it and it broke, chances are that the next guy will run into the same trap -> Needs comment.

So my rule is not to comment anything except to show people around ("this stuff works with that stuff over there to achieve whatever"). Basically the stuff that you simply can't put into code because your language simply doesn't support it.

Then I refactor code to introduce sense (like grouping repeated operations in a method with a telling name).

And when I find code that behaves unexpectedly and I can't fix it, I put a comment in there for the guy who has to fix it (who might be me). In an ideal world, I should be able to fix anything but the day has only so many hours, so something has to give and in this case, it's better to add a note instead of just walking away.

Answer 55

The best programmer I ever met had a script that stripped out all comments. He always ran it before looking at the code. I was amazed.

"The comments never help," he said, "all they can do is convince you that bad code is right."

Answer 56

As many people here have posted, and I totally agree with, you should strive for comment-less code. You're native written language of choice doesn't compile and unit tests don't test it, so it's never going to be as up to date as regular code.

What comments should express is meta-information. I think of it this way. The code itself describes what it's doing. Good structure and variable/method names should provide most of the why the code is doing that. But what it can't express is the next level up; why the code is written that way and not another (for example). A lot of that history should live in the version control history of course, but some of it deserves to elevated to a more obvious in-your face placement. For me, that's what comments are for.

Examples include references for algorithms used.

// This tree traversal is from "Algorithm T", section 2.3.1 of Knuth vol 1. ...

// The rules to determine account eligibility were taken from the brainstorming session with // accounting on 3/23/09 ...

// This is using sort algorithm X on purpose; performance tests on real world data showed // it to be faster than the theoretically faster algorithm Y ...

The third one in particular is the majority of comments I try to make. Whenever there's an obvious way, but it didn't work for some reason, it's good to document that the obvious way wasn't ideal. Otherwise someone might come along and "clean it up" to be more obvious and run into the same issues that you ran into long ago.

Answer 57

When you see the comment and think "No shit...".

I've seen code commented like this before.

if(isset($loggedIn)) { //if $loggedIn is set...
    if(!isset($_SESSION["commented"])) { //if $_SESSION["commented"] is set..
     //tell the user they're logged in but haven't commented
     echo "You are logged in but haven't commented this session"; 
    }
    else { //or...
     //tell them they have commented!!!!
     echo "YOU DID COMMENT!!!";
    }
}
    else { //or...
     echo loggedOut(); //output the function "loggedOut();
    }

Answer 58

// rajan: 9985508700;rajat: 917716100