good post, many folks just parrot the groupthink of writing comments (tests are good though)

I wrote this a little while ago based on the elements of programming style: http://tech.bluesmoon.info/2008/05/commenting.html

Good to know that others feel the same way.

This post misses the most important use of comments IMHO. It's not about explaining what the code does. I agree with you on those points. However, often comments explain unexpected behaviors about the systems being integrated or surprising facts that took a week to debug. You might see a comment like "#We must trim this data to 256 characters or else the MS XML parser will reject it". That seems clearer to me in an English comment than trying to express that with code structure and variable names. In other words, the WHY is important, not the what or the how. Comments are also good for code you tried and have proven to not work to prevent someone redoing that experimentation.

What language denotes comments that way? For Ruby it'd be:

def random_method(arg)
# This is an awesome method
return 4
end

The example in the post is a python doc comment.

@sevenseeker and bluesmoon - Glad you guys liked it.

@Peter - I suppose my example of comparing lines of code was a bit simplistic, because I agree with you for the most part. I do disagree that comments should be limited to the WHY though. Perhaps a better way to say it would be "If you must comment, make sure to point out why you did something." There *are* times when the WHAT isn't clear and you need to both explain the WHAT and WHY you need to explain the WHAT.

@Kurtid - That's Python. If the first expression of a function is a string, it's a "docstring", which is used to generate pydocs. You can also leave inline comments like your example as well.

That's what I figured since Ruby has a similar string setup (http://j.mp/7Qf6fe), but that is just about the ugliest way to comment for documents.

Perhaps you're missing an easier way?

I find that overly commented code can make understanding code more difficult mainly because of the need for more vertically scrolling. Being able to see a method or two in entirety without scrolling does have value.

Also, code with two many obvious comments tends make me ignore the rest of the code's comments. Please don't comment just because commenting everything is "best practice". Choose your comments carefully.

@Kurtis - Nope, that's how you do it in Python. The reason being that the strings are actually available at run-time (stored as an attribute __doc__). This allows you to do things like view the documentation of a function by calling the builtin help function.

Now, as far as the beauty/ugliness of that way of documenting functions, I suppose that's a matter of opinion.

I'm more of the code as documentation method.

I generally think in an OO system, you would make one comment to describe the general function of the class in general, ensure your methods are "intent revealing", and then only comment the gotchas and special cases.

These special cases are the ones that you either do not have time to refactor, or really dense complicated code that cannot possibly be simplified.

The only other time I think comments are appropriate are for Docs... Java Doc for instance.

I really appreciate your description of comments as code smells. I think I whole heartedly agree with this.

Really, the only time I like to use comments is to help myself document what I'm doing/thinking. Sometimes helpful to just write a few notes in inline. Most other times, just skip it completely ... and don't bother to read other author's comments as well.

I like Dennis Ritchie's maxim: "Write clearly - don't be too clever."

Brian Kernighan has a similar quote: "Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it."

I agree that commenting is more of a judicious activity. I think the most important thing about commenting is to comment the INTENT of the code. It explains behaviour that is supposed to be achieved. This helps people know what the code does (when it does it right) and lets people double check behaviour in the event that it doesn't do what it says. I tend to write a lot of comments but they are not "gets x" type comments. They explain a chunk of code or the intent behind it to allow easy browsing.

I highly appreciate self documenting principles (naming variables and functions according to what they do etc) but the key is to use it judiciously. Not just follow the philosophy carte blanche.

I don't always do it right:)...but I try.

Dont blame the coders. Blame the professors. I have lost many marks for not commenting enough. On other occasions, I have been late because of updating the comments after changing code.

And then there is picky teachers. They want them in proper format. Two tabs from left and if more than one line they have to be enclosed in proper comment block. Why? This is for our own ease. Aren't they? Am I writing an essay on fall of roman empire?

How about you shouldn't be in this job if you cant figure out a block of code with a general guiding comment in the beginning.

In past/present, I have been forced to comments like the one below and not to forget that i lost marks on my second assignment cause I thought such a descriptive variable name doesn't need any explanation.

double acceleration. // this stores acceleration
double vf; // final velocity
double vi; // initial velocity

No really tell me why do I need to comment in a program that calculates the time taken for a stone to hit the ground in a free fall.

You could use evidence instead of spouting rhetoric. Hell you could cite something.

You're just spouting without support.

"Myths about code comments" should read "Opinion about code comments"! I can sympathise with many of your points, however you really don't back up you opinion with facts that would lead to that conclusion that these are myths. For example, comments aren't free, BUT they're not expensive either. What is the cost-benefit of adding a comment? How does commenting impact project scheduling? What is the long term impact to a project if a comment is omitted/added? Etc...

Personally, I'd just like to understand exactly when and how comments are useful based on evidence.

My opinion is that comments are useful, BUT, often times we developers get in to a bad habits where the signal to noise in the comments becomes very low to the point they are ignored and left for dead in the source. For example your "get_x()" function is self describing, yet on the other hand, it does not fully document the expected behaviour of the function. For example, should get_x be thread safe? When is the result from get_x valid? What does it return when it is improperly accessed? Is it up to the caller to ensure that the preconditions have been met, or will the function itself perform validation of those conditions? etc... These are mundane questions that developers don't seem to think about enough!

A docstring isn't a comment. A doctstring is for generating documentation. Every function and method and class and module in a public API ought to be documented. Someone using your public API doesn't necessarily have your code and certainly shouldn't have to look at it, so you should provide something describing everything you expose.

This is a separate issue from commenting code, which should be used to explain the code you actually wrote. Many languages have conventions for writing documentation within their comment syntax, but this is still a case where there are two distinct uses.

Peter Lyons hits the nail on the head: comments should explain why you do something, and should be read along with the code.

That also makes the Python docstring example a bit of a problem case: docstrings can be viewed without viewing the code. So, while "This method gets x" is nonsense, something like "this method returns multiplication factor" may make sense. However, that probably wouldn't make sense as a comment.

You're an idiot; you don't even know what a good comment is. Yes, a reader should be able to tell what well-written code is doing. The comments and documentation tell the reader WHY that code is there. Your entire post relies on the assumption that comments explain what something does, which is completely wrong.

Also, your introduction is contradictory and misleading.

@Mike - The answer to that is "it depends". For instance, in Python you also have the option of using Sphinx which is what you typically use to make public documentation. For the most part, I consider docstrings to be comments. Of course, people using pydoc/epydoc might say otherwise. But I personally feel (as a matter of opinion) that it's better to separate your public API documentation from the source code.

Obviously you not worked much on big projects or something that requires you to fix/change code written by another programmer.
Comments should be used as much as possible (but not overused) in most scenatios.
At any rate, its far better to have "too many" comments in the code, rather than too few!!!

Pay no attention any of the nattering nabobs of negativism who replied to your post.

I agree with the spirit and intent of your post.

If you haven't picked it up, you might check out "Clean Code: A Handbook of Agile Software Craftsmanship". It is a good read, and has a section that covers code comments quite well.

Another myth:

All of my code is so readable I never have to add a comment. Just as there is an extreme that all code must have comments, there is this extreme (found much more often in my almost 20 years of experience) that a given developer thinks none of their code needs to be documented - that if you can't figure it out you must be brain damaged. Combine that with people who don't write readable code and you have a much worse situation than too much code comments.

Like any other rule of thumb, commenting code is meant to be applied with judgement and common sense. It is obvious to most devs that you don't need to comment everything. A little less obvious maybe that you should comment code which doesn't have an obvious intent.

Yes, comments generally have to be maintained, just like code, but that doesn't mean you shouldn't use comments - it means you should maintain them, including removing them if they are not needed.

I have seen a lot of Java beans that just had a lot setters and getters. When these were documented using JavaDocs, the write just entered 'sets XYZ' and 'gets XYZ' for setter and getter of XYZ. Lazy and obviously not needed. Now if 'XYZ' is 'customerName' or 'customerAddress' then okay, still no comment needed. But if 'XYZ' is 'factor', then tell me what 'factor' is - is it a fudge factor, is it a multiplier for some computation? If I don't know the domain, and the property isn't obvious, then give me a clue here - just a couple of words is better than nothing.

In general, whenever I see posts like this, they are either in response to criticisms like above where the poster didn't comment some code that wasn't obvious and/or wasn't readable to mere mortals like me, and/or it was in response to some org that mandates every little line of code must be commented. Use your judgement. There are more important things to rant about.

I really like this post as it clarifies a lot of things I remember reading in beginning coding textbooks (though I think some of the modern ones are getting better). The one critique I have is one I have with lots of similar articles regarding code comments, which is that while you underlined all the bad practices one should avoid, you didn't really make an effort to show off the good practices one should use instead.

I know it's probably harder to come up with good examples of comments than bad ones, but there are hundreds of open-source projects out there you could glance through and I know at least a dozen of them are well-commented. It shouldn't be too difficult to find some comments that perfectly compliment the code they were written for.

Other than that though, it's good to see someone taking on those oft parroted beliefs about comments.

While your arguments are valid, they completely miss the main point of comments, which is to eliminate the need to read code AT ALL. Code that has module/class/function comments and code that doesn't are like night and day. With the former, all I have to do is read a few lines of English on the way to the fragment I'm actually interested in. With the latter, I have to exhaustively read the hundreds of lines of code in-between. No matter how well-written - and anyone who thinks the working of their code is self-evident is deluding themselves - it may be, it takes a hell of a lot longer.

Comments are good, if they describe what the code is supposed to do. With the code alone, how do you know whether it does what it is supposed to do, or whether the actual behavior is buggy?

I agree with Peter Lyons above that this article misses the most important part of commenting. The WHY. Additionally, If you're writing API code, you want the documentation to be separable from the code. AS with Everything there is a good and a bad way to do it.

An important idea, one that is generally not supported by a computer language, is the notion of a code "paragraph". Code paragraphs are a sequence of instruction statements that work together to accomplish some larger unified goal within a function. A code paragraph, like a function, is nearly always worthy of commenting, to give a summary of the overall goal (intent), the assumptions on entry and exit, and especially the boundary conditions for input.

I've often dreamed of a system where code comments could be separated from the actual code file. I would love a way to view code without comments in my way. I would also love to be able to comment a block of code inline. My main dream is that if I change a function, it would highlight comments that may need updating.

My dream is basically how Word tracks annotations.

A nice, provocative opinion that has generated healthy discussion. I write comments describing what my code is supposed to do because if I have to change it a couple of years later, I usually don't remember all the details. Don't try to be a hero, leave a breadcrumb trail. The life you save may be your own. But on the other hand, inane comments inserted just to meet a quota impair understanding.

"""Code must always be "self documenting"""

This is completely bullshit. There are often complex code sections implementing complex algorithms where you can not put everything into code. Comments can be very helpful to explain clearly why the code is as it is. This has nothing to do with badly written code. A line of code is cleary not expressive enough for complex scenarios. Overgeneralizing that any code must be self documenting is just stupid.

From the presentation "SQLite: A Lesson In Low-Defect Software":

> Why Put Comments In Code?
> 1) Make the code easier to read
> 2) Engage the linguistic side of your brain

The second point is especially compelling.

Totally agree, as you can see in my own coding style guide. I only comment things that I cannot make clear in the code.

I am agree with you, but sometimes clients ask me for more stupid commented code

Having code comment is not 100% bad.It is giving some impression that you have a complex code.
But you should try to remove code comment as much as possible by making the code more readable/maintainable/simple by refactoring it.

What do u think about the below code
-------------------------------------------------------------------------
// this is the calculation of calculating transaction total;
$a = ($cost*$amount)+0.5;
$toal = $k-$a *(0.3-$4m);

-----------------------------------------------------------------------
$this->calcuateTotal($total, $amount);

private function calcualteTotal ($cost,$amount){
$a = ($cost*$amount)+0.5;
return $k-$a *(0.3-$4m);
}

obviously second block is more readable/maintainable/simple and it doesn't need any code comments due to rafactored it with extract method.

Obviously code comment might be a smell. It tells from where the smell is. otherwise we need to find where the smell comes.

you're a troll. using emacs and "coding" python ... come on :D

In my experience comments are more useful for header files in C, but rarely the source files. In source files it seems comments are most useful for delineating sections inside the file.

Sometimes code is just too complex and/or generic that it requires comments. But code is often better written with appropriately named functions and variables, than a bunch of comments describing over and again what the functions and variables point to. Also when using OO code, comments are redundant.

It should also be noted that, unless your code is only used internally by an organisation, changing the comments probably means you've changed the behaviour of the function in a way that is not backwards compatible with how it used to work. This will seriously piss off anyone who uses your APIs. The presence of comments isn't the issue in this case, it just means the function was badly/incompletely designed in the first place.

Totally agree and it's good to see that I am not the only one who thinks like this. However, a useful case to have code comments is to explain why you have have followed algorithm A instead of algorithm B in a method. Another is when you have an external API i.e. your code is being used outside your organization. For rest of the cases, if the code is written well and particularly as small methods/functions that do only one thing then it speaks for itself.

if you need to comment then its bad code... bad meaning bad in this case.

easy: use short variable names and functions just like natives.
not function doThisRedunantFnordAlghortihm(NARFnotZOONK:String, NOTNARFbutZOONK:Array) but function fnords(string:String,array:Array). avoid globals and shit. most of the times comments are an excuse for long code. the comments dont make the code shorter... they make it longer (if you havent notice) and longer means more complex than before. therefore it makes no sense to comment a very COMPLEX(fnord) part of code. either you can deal with it or you can take a look into the documentation.

comment when needed or #code doesn't speak for itself is my philosophy... but im self taught so ...

This post distresses me, not because it's wrong, but because so many people will use it as an excuse to skip commenting. Programmers are human, and humans are lazy and egocentric, so we don't like to comment. That means we probably have to comment more than we probably want to in order to offset our laziness and egocentricity. Many labor under the illusion that their code is "self documenting" and fail to put in the few lines it would take to clarify intent. Of course the code is self-documenting to the author! S/he just wrote it! But it won't be so obvious in six months.

Please, for the sake of the programmer who comes after you, comment your intent more often than you think you need to.

My view is that commenting is basically a lost art, beginning about the time Unix started becoming popular. Proper error checking and handling was also lost about the same time, though there has been a partial resurgence of late in language such as Java.

On comments: I do believe that there is a balance to be maintained. Clearly, obvious functions such as pure getters and setters of object variables do not need commenting. However, even here you might need to comment any assumptions and you certainly need to comment any derived members.

Methods of any complexity need to be documented as to what is the intended function, the assumptions made (32/64 bits anyone?), and valid range of inputs/outputs - especially if input is not validated. In addition, algorithms used and any special tricks need to be fully documented.

I also strongly feel that comments on variable declarations are needed. While "float acceleration;" may seem descriptive and thus not deserving of a comment, in fact it is missing the most critical information for a physical value - the units. Is the acceleration in m/s^2 or inches/fortnight^2.

Going further, my view is that all current programming languages have failed in one of the most basic aspects of their job of representing the real world in a useful set of abstractions. No programming languages allows any attachment of units to variable or constant declarations - I should not have to guess the units used, and the compiler should validate correct assignment of units throughout the system (including automatic conversion as needed - if an int can be converted to a float, than an inch should be convertible to a meter without me having to explicitly code for it!). Think about the numeric value in your code - how many are truly dimensionless values?