Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

A coworker of mine believes that any use of in-code comments (ie, not javadoc style method or class comments) is a code smell. What do you think?

share

locked by Yannis Rizos Nov 27 '12 at 20:12

This question exists because it has historical significance, but it is not considered a good, on-topic question for this site, so please do not use it as evidence that you can ask similar questions here. This question and its answers are frozen and cannot be changed. More info: help center.

closed as not constructive by Yannis Rizos Nov 27 '12 at 20:11

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.If this question can be reworded to fit the rules in the help center, please edit the question.

44  
I'm going to upvote any answer that says "no". –  NickC Sep 16 '10 at 22:21
107  
Your coworker made a sweeping generalization, which automatically means he is wrong. :) –  Alex Feinman Oct 1 '10 at 17:25
7  
@Mongus, the 17-avoid-comments link appears to be written by a person who have not yet learned that comments need to be on a higher level than can be written in a single source statment. –  user1249 Dec 15 '10 at 23:28
5  
@Mongus, I disagree. The comments in your example is bad not because they are comments, but because they are TOO close to the code which then changes. They should say WHY and not WHAT. –  user1249 Dec 27 '10 at 13:07
5  
@Alex, isn't that a sweeping generalization, which is therefore wrong (resulting in him not being wrong anyway)? –  user1249 Jan 31 '11 at 10:25
show 7 more comments

35 Answers

No, comments are not a code smell, they are just a tool that can be abused.

Examples of good comments:

// I think this is in cm. Further investigation needed!

// This is a clever way of doing X

// The list is guaranteed to be non-empty here

share
show 4 more comments

However code that cannot be understood at all it a much bigger code smell…

Please give me clean code to work on, however
if that is not an option, I would rather have “dirty” code with comments
than dirty code without comments.

share
add comment

Most of the words have been taken out of my mouth. But I suppose to sum it all up: the point of comments is to give a high-level description/explanation of what the code is doing.

Moreover, here are a few examples of how I use comments:

  • as headings, to indicate the general purpose of a section of code
  • to note where I have cribbed code from and thereby avoid plagiarism
  • occasionally at the ends of blocks, to remind of what block they're the end of
  • to point out that code that may look suspicious is what's intended (e.g. those odd times when a switch case falls through)
  • to explain the maths behind an algorithm
share
add comment

No one said this so far in this thread, so I will:

Type names, variable names, function names, method names and comments are just metadata about your code, and has nothing to do with the machine code that the compiler generates (except the names of the exported and debug symbols of course).

Type names and variable names are your nouns, function and method names are your verbs, with these you describe steps to be done. Comments are for everything else.

Some examples:

double temperature; // In Kelvins.


/**
 * Returns true if ray hits the triangle
 */
bool castRayOnTriangle(Triangle t, Ray r)
{
    //...
    if (determinant == 0)
    {
        /* The ray and the triangle are parallel, no intersection possible.*/
        return false;
    }
    //...
}


/* X algorithm. Visit http://en.wikipedia.org/... for details.*/
<implementation of something difficult to understand for the layman algorithm. >

Comments may bacome obsolete, if not updated, but variable and function names can become obsolete too. I recently encountered a bufPtr field in a C structure, which has nothing to do with buffers or pointers. And I saw a inflateBuffer function that does not decompress a deflated data but a complete GZIP file... These are as annoying as outdated comments.

share
add comment

It doesn't seem like too many answers consider programming in teams. I'm a senior developer and I tend to write comments aimed at explaining what is otherwise simple for me to understand.

I see it as a form of posthumous team communication or education. I encourage the team to look through code they are using, but maybe haven't written to understand it better.

A couple of examples just from this week (PHP code):

//Pattern for finding jpeg photos
//Case insensitive pattern for jpg and jpeg
const PATTERN_PHOTO = "*.{[jJ][pP][gG],[jJ][pP][eE][gG]}";

I'd hope the name PATTERN_PHOTO would be helpful later in code to explain what it does, but without the comments how clear would it be to a junior developer what this specific pattern does?

Same set of code:

//Ignore . and .. directories in Linux
if($file != "." && $file != "..")

There's an expectation that our developers know PHP, but not that they understand the Linux OS we are using for hosting.

So, I find these comments to actually increase the overall efficiency of our team for the very little time it takes to write them.

  • There's less cases of people rewriting code simply because they don't understand how it works. "I didn't understand how it did what it was supposed to, so I fixed it." Seriously, I've had to deal with this before.
  • There are less questions asked about individual pieces of code. Answering the questions just once, usually requires looking up the code and the time for me to re-familiarize myself with it. And sometimes I'll get the same question from more than one person weeks apart. (Yes, it would be on things as simple as the examples above)
  • Other developers are encouraged and guided to learn on their own. I'd expect that if they came across //Ignore . and .. directories in Linux they'd likely hop on Google and would suddenly understand Linux a little bit better.
share
add comment

Not the answer you're looking for? Browse other questions tagged or ask your own question.