“Comments are a code smell” [closed]

Question

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?

Answer 1

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

Answer 2

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.

Answer 3

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

Answer 4

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.

Answer 5

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.