Myths About Code Comments

theodp writes "Jason Baker gives his take on the biggest misconceptions about code comments: 1) Comments are free ('When you update the code that the comment references, you usually have to update the comment as well'). 2) Comments make code more readable ('by far the most pervasive myth that I've encountered'). 3) You should comment every function, method, class, and module ('documenting something that needs no documentation is universally a bad idea'). 4) Code must always be 'self documenting' ('would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments?')."

Comments

One person's myth is another person's fact.

[yog]

Well, everyone's welcome to their opinion, but it's pretty well proven after decades of software engineering that code should be commented. The price of maintaining comment-free code is well known.

There is a school of thought among programmers who consider themselves hotshots that if you are not a hotshot you have no business touching their code. The problem with this attitude is that it has little to do with the real world, where people change jobs and programmers inherit someone else's code. If you want to write perfect, comment free code in your perfect little world, go right ahead, but don't expect to make a living at it most of the time.

It's surprising to me that someone has submitted this as a "news" item. News flash! Everything you know is wrong. Sorry I don't buy that. If you don't comment your code, I won't pay you for it. I'll inform the management that you neglected an important step and don't deserve a good reference. I won't be able to give you the benefit of the doubt when your code doesn't make perfect sense. I'll trash talk your code in front of your colleagues. Look at all the mistakes in this guy's work; I'll sure never recommend him if his resume crosses my desk. We may need to just rewrite this stuff because it's not maintainable as written.

What's really annoying is when they put comments that don't elucidate the code or their intent; they're just snide little messages from one know-it-all to another. They're too embarrassed to actually explain the code because that implies a level of insecurity they would rather not admit to. So instead they say things like: /* yeah, I don't like this either */
or
# hack, to be fixed later

Wooooo, really helpful comments there. I've seen this sort of thing countless times in my career and most others I know have as well.

Re:One person's myth is another person's fact.

[Brian Gordon]

Woooo, business programming. Believe it or not, there are a few applications out there that require performance and cleverness rather than strict convention. I think that a myth of software development is that every line of code should always be simple and easy to understand. Sometimes things are complicated, especially in performance applications.

Re:One person's myth is another person's fact.

[MichaelSmith]

I work on a really big hunk of C code and one place I would like to see more comments is in the start and end of blocks. This is because during the life of the code people come in and paste maybe 1000 lines of code from elsewhere into the block and totally stuff up the indenting so its hard to see what is supposed to match to what. This is particularly a problem with importing between branches (my job at the moment) because it can be hard to work out the original intent of the various nested blocks you wind up with.

Commented out code is a particular problem because my editor can count { and } but it doesn't know if some of those have been commented out, possibly asymmetrically.

Where I work comments get used to abuse people. You commit a message:
 
/*Hey $YOU dont do this again */

But a lot of the comments we have I can't even read because they have been collected by the code in one of the countries it has been to over the last 30 years or so. Many of them seem to be in French and Arabic.

Re:One person's myth is another person's fact.

[khallow]

Even the "this is a hack/kludge/abomination unto nature" comments are useful to me. It tells me some starting points for improving the code. Also I write similar comments to remind myself where the iffiest parts of my code are.

Re:One person's myth is another person's fact.

[WED Fan]

In your race to be first, you failed to read the article.

Re:One person's myth is another person's fact.

[93 Escort Wagon]

Even the "this is a hack/kludge/abomination unto nature" comments are useful to me. It tells me some starting points for improving the code. Also I write similar comments to remind myself where the iffiest parts of my code are.

I agree. When I put those sorts of comments in, they are most often notes to myself rather than a legacy left behind for others.

I prefer to write code that's easily extensible, and in most cases it's what I try to do - but that definitely takes longer than hacking something together (at least for me). Since I'm not the boss, there are times when I've been given direct orders to "just get it done so I can show this to xxxxx, we're never going to need to change this anyway" - and I do it. Down the road I try to fix those when I'm in a slow-ish period; but also, they are valuable reminders when, a year later, the boss comes back and says "can we add yyyyy and zzzzz to that?" because it a) gives me a chance to talk with him about why I prefer writing it right the first time; and b) provides support for telling him why it'll take me a few days to add those features rather than the 1-2 hours he thinks this "minor change" should take.

On a side note: There's nothing worse than running into someone else's 6-7 year old bit of code containing comments like "hack, important to fix this next revision" - it's too much like finding those silly "under construction" animated gifs on a web page that was last updated in 2003.

Re:One person's myth is another person's fact.

[SanityInAnarchy]

There is a school of thought among programmers who consider themselves hotshots that if you are not a hotshot you have no business touching their code.

I don't see anyone claiming that here.

If you want to write perfect, comment free code in your perfect little world, go right ahead,

Nor that. At least Read The Fine Summary (attempting to increase my character-per-line count to avoid lameness filter):

documenting something that needs no documentation is universally a bad idea

And from The Fine Article:

Comments don't make code more readable. They are ways to compensate for code not being readable.

Which does happen. Again, from The Fine Summary:

would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments?

But probably the biggest thing you missed is right at the top of The Fine Article:

It seems to me getting good at writing comments is an under-appreciated part of a Programmer's development.

I actually agree with most of what you said, but I would fix this for you:

If you don't document your code, I won't pay you for it.

Self-documenting code is a reality. It does work. And if you're going to carry out all your threats simply because I didn't do this:

// Gets the id
public int getId() {
return id;
}
// Sets the id
public int setId() {
return id;
}

In that case, yeah, it sucks that I don't get a reference, but I'd be glad to be unemployed again, looking for a job where I can do this instead:

attr_accessor :id

Part of the reason I suspect you have a problem:

What's really annoying is when they put comments that don't elucidate the code or their intent; they're just snide little messages from one know-it-all to another.

You seem to have a healthy dose of envy and disdain for the people who work under you. You're also missing the point:

/* yeah, I don't like this either */
# hack, to be fixed later

The first is a potential problem, but a little humor from one developer to another... Sometimes the code is a mess, and no amount of comments will help that. The best you could hope for is "I don't like this, and here's why:", or "This is how it works... I know, I don't like it either."

But that second comment, "hack, to be fixed later"? You should institutionalize that, because it is, in fact, a good practice. Make them do this:

TODO: fix this hack later.

Then have your CI system automagically create tickets for that -- they are indeed bugs, and should be fixed. But they aren't just bugs in documentation -- you should be removing hacks in the first place.

But if your developers feel they have to write a quick hack instead of Doing It Right, it's probably not their fault, it's your fault as a manager for setting unreasonable deadlines. Requiring them to thoroughly document their hacks isn't going to improve things, it's going to take time away from real work, resulting in less good code, and more hacks -- maybe ultimately reducing your program to a single 300 character long regular expression, but man, is it well-commented!

And you are again missing the point. The point is not that we are hotshot programmers who don't think non-hotshots should be messing with our code. Rather, we are competent professionals who expect people to understand the basics of the language before reading our code, and even then...

class Story
has_many :comments
belongs_to

Re:One person's myth is another person's fact.

[SteveWoz]

Both the code and the comments should be as understandable as possible. Don't forget that the effort to comment well helps the programmer in his/her own thinking and his/her own understanding of their own code, and helps in development of good code that doesn't have bugs.

Re:One person's myth is another person's fact.

[Nutria]

Sure. It's a damned fast way to multiply or divide by a power of 2.

I'd never do it in a DP shop, though...

Re:One person's myth is another person's fact.

[Tanuki64]

I work on a really big hunk of C code and one place I would like to see more comments is in the start and end of blocks. This is because during the life of the code people come in and paste maybe 1000 lines of code from elsewhere into the block and totally stuff up the indenting so its hard to see what is supposed to match to what.

If the only tool you have is a hammer, every problem looks like a nail. You comments are in this case the nail you desperately want to hammer in, when in reality you need a refactoring. And you need to give the idiot, who pastes the additional 1000 lines, a hearty kick in the ass.

Re:One person's myth is another person's fact.

[hedwards]

OK, this topic is officially over. That's the nub of it, if a programmer could intuit what would be confusing a decade down the road or to another developer that takes over, then you can cut out on the comments. The cost of documentation does exist, but people ought to be thinking twice before putting in overly complicated, absolutely must comment code. Sure some cases require that for legitimate reasons, but most of the time you're doing it wrong, and putting in the comment gives you the opportunity to reconsider whether that complex code could be simplified.

Re:One person's myth is another person's fact.

[Nelson]

What did this blog writer actually ever do that's worth a shit? Shouldn't that be one of the first things mentioned? Far as I can tell, he's a nobody that writes a blog. I can't find any references to any important pieces of software he's worked on that makes me think I should give a shit what he thinks. Moreover, the ideas he's propagating are bullshit, what he says is true if you don't write software, don't work on important software, and don't play on teams, otherwise it's just stupidity and he's showing his youth. Nothing to see here, move on.

Taco, Hemos, Slashdot, et al.., remember way back in the day when we were infested by all those Katz articles and so they implemented the Katz-block technology to let us remove that crap from the front page? I like the developers section but this is a bullshit article, we need to introduce a more fine grained Katz-block. We need an "everything you know is wrong" subsection, a "new language or some shit like that" subsection, and a "technology x is dead" subsection so I can block that crap out of the front page.

Re:One person's myth is another person's fact.

[Surt]

Most are not hot shots. We have a programming test for applicants to my company. It is really close to trivial. 4 out of 5 applicants for the job of senior software engineer submit a solution so bad they are dismissed immediately. Out of the remaining 20%, only about 1 in 10 submits a solution I consider 'good' (and is therefore a person I consider a possible hot shot candidate). The rest are merely adequate and clearly not hotshot material.

So that's 2% hotshots at best by my reckoning. Of course, this ignores the fact that our trivial programming problem probably pisses off a few hotshots enough that they don't submit, but we don't want to hire that kind of personality, hotshot or not.

Re:One person's myth is another person's fact.

[GeckoAddict]

This is because during the life of the code people come in and paste maybe 1000 lines of code from elsewhere into the block

Your design is horribly wrong.

so its hard to see what is supposed to match to what

Branches or not, you need a coding standard, fast.

Where I work comments get used to abuse people.

Your development team is in need of some management and/or personal communication skills.

Re:One person's myth is another person's fact.

[daVinci1980]

I say this in a slightly different, but more concise way:

Comments (and self-documenting code) should tell you "what" and "why", because the code is telling you "how".

Re:One person's myth is another person's fact.

[jythie]

And if your resume passed my desk, you would not be hired.

I have to ask.. what in the world is your problem? It sounds like you wish to torch anyone who does not use the exact amount of commenting you do. Engineering is about tradeoffs, and comments are no exception, that is all the piece said.

It did not even say 'do not comment', just to be aware of the cost/benefit and make a decision based off that.

If you are encouraging people to take a blind dogmatic approach rather then doing the work to determine what the appropriate amount is, then I question how effectively you can apply it. To be blunt, it makes you sound like another type of hot shot that is an equal bane to the ones you are complaining about.

Re:One person's myth is another person's fact.

[honkycat]

My opinion is you're a stubborn idiot.

Dude, don't be an asshole. Especially when you're about to chastize someone for making assertions and then respond with an even less substantiated steaming pile.

Comments like "yeah, I don't like this either" or "hack, to be fixed later" indicate your team didn't have enough time to do it the right way the first time. It's a warning to whomever makes changes later that something is amiss. If the coder knew what to comment which might be helpful, they'd probably go ahead and implement it. Perhaps you'd like to see "optimize this" or "I have to stop working on this so I can finish my commenting before peer review so we can meet the deadline."

No, comments like that are absolutely useless. When you write them, you know the context a lot better than someone who comes in to debug or extend it months or years later. Obviously you recognize there is or may be an inefficiency fragility to the code. Not having time to sort it out is understandable. Not having time to properly note what about the code is fragile or inefficient? Sorry, that's utter bullshit. Take the three minutes necessary to give the reader a proper explanation of what you don't like about it. "This fails if X possible but unlikely condition occurs," "This is unacceptably slow when more than N rows are returned because of Y," or something is more like it. "I don't have time to be helpful" is a lame excuse for not being very good at your job.

You want a theoretical team which updates comments along with the code, and all peer reviews catch any outstanding comments, your costs are going to skyrocket. The real world requires lots of time to ensure documentation stays up to date, and your focus should be primarily on anything used by external users, second on internal documentation like design or event mapping, and last on code. If you have time and money left.

Yes. The real world requires documentation be kept up to date. Yes, documentation is part of the cost of coding. It takes more than writing code to built a non-trivial program. What's your point?

I really don't understand your position. Looking through the blustery hot air you felt it necessary to inject, you seem to understand that comments and documentation are important when necessary. But then you suggest that useless "fixme" comments are ok? And then you say crap like, "Every compiled application out there is completely documented."

Like you, I'm not a fan of large, boilerplate comments as a rule. However, having reviews that determine whether code is sufficiently commented is quite reasonable. After all, the original programmer is just about the worst person conceivable to determine whether his code needs a comment. Of course it makes sense to him, he just wrote it.

Looking at your examples of cases when comments are/are not needed, I find it amusing that you suggest an external design doc as being preferable to in-code comments, since the effort and cost of keeping this consistent is orders of magnitude greater than for comments. (I don't necessarily disagree, I just find it discordant with your comment.) Obviously endless get/set methods don't need much in the way of comments. But if that's the bulk of your code, you're not doing much. For non-trivial functions and code, I find it very hard to believe you can get away without most of your functions having a header comment that explains the purpose of the function, or at least the meaning and ranges of the arguments.

That has no place in the real world, and maybe neither do people like you.

Nyah nyah nanny-nanny-boo-boo neener neener. Grow up.

Re:One person's myth is another person's fact.

[Surt]

Absolutely. Other people, who are not geniuses, will have to maintain the code for years. They must be able to understand it. Someone who is capable of writing something that is incomprehensible to me, and who can't foresee the problems with that is of no value to us.

Re:One person's myth is another person's fact.

[Radres]

"Write-only monkeys"? While I think it is expected that a programmer should be able to figure out a given piece of software, even undocumented, given enough time, I think it's a bit severe to expect that any piece of non-trivial software can and should be figured out from raw disassembled code 100% of the time. Just thinking through some of the headaches I've encountered with spaghetti high-level code, I can't imagine trying to decipher that same code at the assembly level, nor how it's a good use of someone's time to have to do so just because someone else couldn't be bothered to comment their code.

The best technique I've learned is to first write out in English a comment describing what you are about to write in code, then write the code after the comment. If you can't explain what you are going to do in English to begin with, you probably aren't ready to write the code. Doing it this way doesn't cost you that much extra time in the long run, since about 80% of your time as a coder is spent thinking about the problem, and only about 20% is actually writing it up. When done, your code will have a nice natural flow to it, and it will be obvious where you should break out new methods to increase the understanding of the code.

Re:One person's myth is another person's fact.

[12357bd]

The best technique I've learned is to first write out in English a comment describing what you are about to write in code, then write the code after the comment. If you can't explain what you are going to do in English to begin with, you probably aren't ready to write the code.

I fully agree with the basis of your position. After more than 30 years programming, the way I like to comment my code, is attaching a comment for every instruction. The intention is to explain in plain words what code is doing at every step, and larger and broader ideas on the heads of functions and/or definitions/classes.

The result is verbose of course, but it can be read linearly, and the underlying algorithm is fully explained. The reader have a plain explanation of the why's and the how's of the code.

Re:One person's myth is another person's fact.

[cloudmaster]

To demonstrate why other people might be able to solve a problem you've been stumped by, lets look at the "mv | cat | grep" you provided. :)

First, that doesn't check the return value of the mv, so if the mv fails, you'll just clobber the original file. And, piping mv is just dirty. The Borne shells provide && for that:

mv && cat | grep

So, we have a check that the mv worked before clobbering the original now. This is a good start. But, that removes the original and recreates it - so you're probably mangling the permissions. If you do a cp, you have two gains - you preserve the original permissions of the file, and you guarantee that there will be enough space for the new file (since it'll be smaller or the same size without any comments). So, now we have

cp && cat | grep

Finally, the "cat | grep" construct bugs me. Grep takes filenames as arguments; it doesn't have to read stdin. So the cat and pipe is spawning a new process and setting up extra file descriptors which are superfluous. The performance difference is negligible on a one-liner, but if this same construct is used in a tight loop, it adds up. It's basically a bad habit. Just use grep. :) So, ultimately, we have an optimised version which is notably more robust and faster and less to type:

cp src src.orig && grep -v "^#" src.orig > src

But wait, there's more! If you're using bash or ksh93, you can use shell word expansion to reduce the chance of typos:

cp src{,.orig} && grep -v "^#" $_ > src

And then, say you're sick of all this junk and just want to do it with one command that's shell-independent. Well, lets use perl:

perl -i.orig -lne 'print unless /^#/' src

So anyway, don't assume that someone else can't solve a problem more elegantly than you.

And don't take this post too seriously. ;)

Re:One person's myth is another person's fact.

[Anonymous Coward]

What did this blog writer actually ever do that's worth a shit? Shouldn't that be one of the first things mentioned?

Maybe some of us prefer to judge an argument on its merits, rather than whether we like the person who made it.

Cliche, but true...

[Xaroth]

Clean code tells you how, good comments tell you why.

Fixing the "how" becomes significantly easier when you know "why" the code was there in the first place.

Re:Cliche, but true...

[Anonymous Coward]

This is absolutely true and even how becomes more important with lower-level languages where the code probably will not imply the intended outcome. Try figuring out clever assembly code without a running commentary; it's not fun.

Re:Cliche, but true...

[Brian Feldman]

Clean code tells you how, good comments tell you why.

Fixing the "how" becomes significantly easier when you know "why" the code was there in the first place.

You seem to be implying here that good comments cannot explain how something non-obvious works. Often in software there are tricky sections of code that benefit from both comments explaining why a given algorithm is implemented but also how the control flow works. Comments are also extremely useful to mark spots that need attention later but are sufficient for now, and also to document any type of "contract" that a particular body of code adheres to.

Re:Cliche, but true...

[Wraithlyn]

Indeed, and perhaps it's an obvious point but I'd also add that clean code should also tell you "what".

Whenever I have a block of code whose purpose seems unclear, I try to put it into a function whose name clearly describes what it does. This immediately makes it more understandable, and reusable to boot.

Comments should explain why something is done the way it is, the reasoning behind it. They should not simply label what something IS, that should be the job of good naming practices.

Re:Cliche, but true...

[dkf]

In most high level languages, description method or function names tell you why as well.

Function (and argument) names don't tell you the why of the function. They tell you why you would call the function. That's an important difference. (For example, a function might be called GenerateUniformRandomNumber(int from, int to), but that does not say anything about the particular algorithm used to do the generation, which might need a few references to the literature on PRNGs to do properly.) If the code has description metadata attached to it then that's quite possibly containing a lot of what is considered by others to be "comment" (even though it's not actually one).

Re:Cliche, but true...

[Slackcity]

Right there.

Intent.

If I don't see that in comments...

Re:Cliche, but true...

[DrKnark]

In certain IDE:s those types of comment are helpful. Mousing over a function call to see what it returns and what the arguments are without having to find the code for that function speeds up coding for me personally at least.

Wrong on all accounts

[smartin]

Having worked as a programmer for many years, all I can say is poorly commented and undocumented code is unprofessional and I would rather
rewrite it than try to decipher it. I've heard all of these excuses before and all I can say to the people that make them is: Your code is not as
good as you think it is.

Re:Wrong on all accounts

[TheRaven64]

Your code is not as good as you think it is

Even if it is, the person reading it might not be as good a developer as you, or may be as good (or better) but with different experiences. In both cases, they may not be able to read and understand your good code without comments. When they change it and it breaks as a result, then it's your fault.

Re:Wrong on all accounts

[Nerdfest]

You shouldn't need to decipher the code. Most of the problem is not the missing documentation, but the poorly written code.

Re:Wrong on all accounts

[jbolden]

The next programmer in line may not need to understand the complex multi threaded stuff at all. For example he may be revising the UI or the backend datastore. Reading your multi threaded comment may be effectively him just having a comment that the is no I/O and that the block is all CPU / memory; and that is good enough.

Re:Wrong on all accounts

[0xdeadbeef]

If you have to "decipher" code, it is wasn't good to begin with. I used to believe the comment religion, it was beat into us in school, but once I started working with people with similar or greater skill than mine, I noticed that comments became few and far between. Usually they are only necessary to explain the intersection with something external or poorly designed, such as an API call or hackish work-around. Comments are no substitute for not knowing the problem domain. If you need to educate a new hire, you should already have documentation that explains the architecture.

If you want to talk unprofessional, the absolute worst are comments that state the obvious. It's like watching a movie with an imbecile talking to the screen, telling himself everything that is happening. It goes without saying that those comments are usually uncapitalized, lacking punctuation, and full of misspellings.

Has No One Actually Studied This?

[Greg Hullender]

In thirty years of programming, I've heard one person after another argue about how to comment and how much to comment, but what I've never seen is any kind of serious study attempting to measure what actually works best. I personally like to make comments paragraphs, not lines, and generally end up with code that's 1/3 to 1/2 comment lines, but the most I can claim is "it works for me."

I do think good commenting has to be a key part of software engineering (when it finally becomes a real engineering discipline), and I know software engineering is a hot topic these days, so perhaps there's a paper on this that I just haven't seen yet. If not, someone really ought to do a serious study. And then start teaching people something that's actually known to work.

--Greg

Re:Has No One Actually Studied This?

[tomhath]

A former employer (a very big multinational corporation) did a study that tried to correlate the number of comments in code to the number of problem reports against it. Not surprising to me, they found that in general the more comments in the code, the more problems were reported against it. That was my observation as well; bad programmers couldn't figure out a straightforward solution to a problem so they wrote messy code with lots of comments trying to explain what they were doing. The really good programmers wrote simple clean code that only needed a few comments.

Another characteristic of bad programmers that I noticed was their tendency to keep copying data from one data structure to another instead of using it in place. Obviously an indication of bad design, and it introduced lots of bugs. You knew as soon as you opened a source file and saw comments like "Copy blah-blah data from abc array to xyz array" that you were in trouble.

Re:Has No One Actually Studied This?

[JetTredmont]

It's funny, a lot of the examples you see on MSDN and similar are often not very commented. I'm not saying this always produces readable code, but as the examples are "at the correct level", it tends to be quite readable.

There are three factors at play there. First, more comments means more lines of code, which makes a "simple" example seem larger. Second, it's a lot easier to explain how an example works in the text surrounding that example (in the overview document for MSDN, or in the non-code portion of a tutorial, etc). Long-form text is much easier to read with a proportional font and paragraph structure. Also, it's often NOT the original developer of the code entrusted to writing the documentation. Third, and importantly, these are generally relatively trivial pieces of code.

From my personal experience, such snippets of code tend to be pulled from larger works, and have a "simplification" process where both any hooks to the rest of the system are simplified (preferably entirely away) and all comments are removed (the tech writer working the tutorial might preserve these comments to make sure they cover the bases in the tutorial/etc). As such, it's no accident or coincidence that they have few if any comments left once published. It doesn't necessarily indicate that the original code was comment free (although that may have been the case).

In one system where I work there are hundreds of pages on deployment procedures. In ours we managed to automate 99% of the process. Which would you rather have?

I'd rather have the procedures automated with well-commented code. Because no matter how well your code is structured, the realm outside (the process that your deployment process fits into) is not so neatly structured.

I don't see how arguing for/against intellisense fits in here. I love to use intellisense (er, well, the non-Microsoft trademarked variety), AND I love to have comments in code I am scanning when looking for a bug or a way to fit a new needed feature in.

Re:Has No One Actually Studied This?

[Anonymous Coward]

I think you may have the cart before the horse.
Code which is doing a hard job, often needs more comments because there are more things to keep in mind when working on it. it is also more likely to have problems.

I have been programming for more years than the age of a large portion of the readership of slashdot (34 years), and I can tell you that when you come across your own code twenty years later, you have NO IDEA about what you were thinking when you wrote it. After years of experience I have decided that code should be rejected if you can not tell what it should be doing AND WHY without actually looking at the code itself. The comments should form an independent summary of what the program should be doing, a bit like the "director's commentary" track on some DVDs.
Think of them as an error recovery track.

I recently started work at a new company and to my dismay found that much of the code was uncommented. I estimate it slowed down my understanding of how the product worked by several hundred percent. And yes, somewhere, you have used my code, whether you knew it or not.

Re:Has No One Actually Studied This?

[digitig]

Yes, but the reason CS students talk about sort algorithms is that they're a convenient didactic example that everybody can understand. If I'd taken an example from the actual stuff I've worked on, most people wouldn't know what I was talking about.

More verbose == less readable?

[nmb3000]

I disagree with this general statement:

For instance, would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments? In most cases, code's readability suffers more when it's overly verbose than when it has a high comment to code ratio. Thus, I would choose to write the comment in most cases.

First, I think any time you consider writing some clever one-liner in real production code you should rethink long and hard. Is the hypothetical 6 fewer lines of code really worth it? Unless you're doing it for absolutely required performance reasons, the 6 lines of code you save won't buy you anything but the wrath of whoever has to come along in 3 years and refactor your code.

Of course you can be too verbose, but it's a much rarer problem than the alternative. Even overly verbose code is usually easier to understand, easier to maintain, and easier to refactor than that clever little one-liner. And if you're that worried about a verbose section of code, extract a method, give it a good name, and be done. Now you have both a one-liner method call that is easy to read in context and a more verbose implementation that is easier to understand and maintain in the future.

In other news...

[CAIMLAS]

In other news, people have personal preferences, just as they do in the literary world. Some people like Ayn Rand, others hate her. Some like Stephen King, others hate him. Not so much their stories, but their writing styles.

Snowcrash is an awesome story; one many can appreciate, but most people couldn't get through his writing style to finish the book.

I think that if more people wrote code (or, for that matter, books) like George Orwell wrote his books, code (and books) would be generally more readable: shorter sentences (lines of code) which convey a single meaning (function), strung together into short paragraphs (code blocks), chained together into a larger cohesive whole.

Comments are not design

[Anonymous Coward]

Code that has concise, sensible comments is indicative of a good design. However, I don't care how 1337 you are, no professional developer worth a damn programs anything bigger than a 3-line batch without at least some sort of design document. Comments that relate back to the design document are one thing, but it is really hard to use comments to point out the design of a program which had no design other than "I am ok to just wing this because i am 1337."

Please no

[dachshund]

Christ, I know everyone has their own personal style and everything, but this is just pernicious. In any case, the author gives the game away: when he thinks code is overcommented, he can ask Emacs to hide the comments. So far as I know there's no automatic system that will generate the comments that the author failed to put in because the code was "self-documenting". This is particularly important when you're working with anything other than standard libraries --- you might know what "libfzp_inc_param_count_fast", but your reader probably won't.

Right now I'm working on a crypto library that incorporates a lot of very specific elliptic curve operations. My technique is to comment the hell out of every damned interesting piece of code on the assumption that a picky reader can turn off the damned comments if they get in his way. In fact, there are various places where I've actually scaffolded all of the comments before writing a line of code. Doing otherwise would have been an enormous headache and made bugs a whole lot more likely. And this way even a non-expert should be able to understand the entire program flow.

Unfortunately, one of the previous pieces of software in this area followed the poster's "self documenting code" style (very nice, clean, well written code with no comments), and even I find it difficult to piece together what's going on in places --- not because all of the code is crypto-specific, but because the author has thrown so much effort into writing "clean, pretty" code that it's actually hard to know where the crucial pieces are. I can't quite explain why I find this so irritating, but perhaps some of you will know what I mean.

Re:Please no

[Anonymous Coward]

A smart optimizer will inline where appropriate. Of course, relying on the optimizer is not always the right idea, but unless you know it is a problem, it is usually the right idea. Also, you can mark functions as inline in C (and probably other languages) if they are logically separate functions, but should not really be called as separate functions. Of course, as you note, separating out functions where the pre-conditions are very precise and non-obvious is going to cause maintainability headaches.

On recursion, it is generally a much cleaner way to express an algorithm and easier to write proofs about. Also, if the function is tail-recursive (its recursive call's return value is always immediately returned), then even a very simple optimizer will always turn such a function into a loop as the transformation is trivial. Unfortunately, in the real world, tail-recursive functions aren't actually that common, especially as any error checking on the result nullifies the tail recursion assumption.

Choice of Language

[mandelbr0t]

It really depends on what language you write your code in. Object-oriented languages in general require less documentation since good design and properly named methods and properties do document things relatively well. Class-level documentation is much more important than documenting the details of the methods themselves. Java and .NET require much less documentation to maintain. I've looked over Java code I wrote years ago, and it still makes perfect sense, even though I've only really documented the API and not the details. Perl and C code, on the other hand, can be unmaintainable even with a number of comments, because the old functional design is not easily maintainable. Consider rewriting these in a more modern language.

Call me a hotshot if you want, but I shouldn't have to assume that the person maintaining my code is a moron, nor that my non-technical manager needs to understand every single statement I wrote. I play nice with QA, and happily write test cases for my code. That's as far as I'm willing to go to ensure that my code quality is good, and that I can leave without the possibility of my code degenerating into the spaghetti-like mess I've had to clean up on a number of occasions. Sure, I don't get hired to write code anymore, but I don't care. Software Engineering and overdocumenting every single tiny intranet project is wasteful. Cleaning up after morons who believe that their engineering background can make up for their lack of talent and experience is aggravating. Answering to them is intolerable. There's other things I can do with my technical background that don't involve butting heads with people who dogmatically apply software engineering methodology to everything they do. It's their loss, not mine.

So who is this guy?

[anti-NAT]

No offence intended to him, but he's just re-interating the sort of commentary on commenting that's in Code Complete, The Practice of Programming, Linux kernel CodingStyle etc. He's not offering any original insights, or telling war stories that people can learn from. Any decent programmer would already know these myths, and if they didn't, they really should be reading books such as the ones I've listed, not a blog entry with very little original content.

IOW, what makes special enough to be Slashdot front page news?

"would you rather use a one-liner"

[lax-goalie]

would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments?

Easy. 10 lines, no comments. After writing a couple of million lines of code, the more code I write, the more I unwind it. Somewhere along the line, adolescent programmers got the idea that jamming all your logic into as few unreadable lines as possible is the fastest way to manliness. Way, way wrong.

Modern compilers and interpreters do a pretty good job nowadays. Source code bytes are near free. If you have to skull out dense code 6 months after you've written it, you're doing something wrong.

(OK, Lisp and APL are special cases, but really, when's the last time you wrote Lisp or APL, other than for fun?)

You made his argument for him

[dreamchaser]

Woooo, business programming. Believe it or not, there are a few applications out there that require performance and cleverness rather than strict convention. I think that a myth of software development is that every line of code should always be simple and easy to understand. Sometimes things are complicated, especially in performance applications

GP never said that (re:bolded text), and the point you are trying to make makes a strong argument FOR clear, concise comments on code. Good code isn't always easy to read at first glance and appropriate comments are important in any project with more than one programmer.

Re:You made his argument for him

[DG]

Indeed.

Sometimes there is a very good reason for including clever, non-intuitive code in a project. But that clever code needs to be very well documented because the next guy to touch it may not be that clever.

When in doubt, optimize code for future maintainability and legibility. Hardware gets faster. Programmers don't.

DG

Re:You made his argument for him

[pz]

I can't count the number of times I've written a very carefully researched small handful of lines of code that are either not intuitively obvious, or would leave more questions than they answered when read. When I've spent days demonstrating through thorough measurement that, for example, a certain constant requires a specific value, that fact gets documented with potentially many paragraphs of comments. Not doing so would be irresponsible, and a waste of my time when I tried to understand, months or years hence, why I had written that small handful of lines.

To quote one of the Ramones who was criticized in an interview for writing songs with only three chords, "yeah, but they're the RIGHT three chords." With music you can feel if the chords are right. With code, sometimes you have to document.

Not commenting is a sign of not thinking or caring

[presidenteloco]

If you don't header-comment your class or public method,
I have to conclude that you cannot articulate what it is or what it
means or is for. So probably the code is incoherent/inconsistent too.

So that's going to make me write my own instead of using your code.

Or maybe you can articulate what it is about but are borderline
autistic and don't see the need to communicate meaning to others.
To me this just means you are so inexperienced in programming that
you a) don't understand the costs of maintenance, and
b) don't even realize that you yourself aren't going to be able to figure
out your code in six months.
Either way, I'm not using that code if I can help it.

Re:Over documentation is good

[jocabergs]

I think over documentation isn't on the whole a bad thing, but there have been a few times where I've been more confused by the comments than the code. I don't care if people get clever with code and have clear comments, but I hate when people try to have clever comments, comments are not supposed to be hard to understand.

Strongly RESTRICT Code Commenting

[omb]

There are just 3 good reasons for comments in code: (a) to refer to a published paper describing an (obscure) algorithm, eg '[fast graph traversal algorithm, M. M. Balakrishnarajan and P. Venuvanalingam ,Computers & Chemistry, Volume 19, Issue 2, June 1995, Pages 101-106] , (b) to indicate an arcane, obscure usage, which would be better eliminated, but sometimes cannot be eg in device drivers, when merely addressing a device register has side effects, (c) to very briefly document major parts of program flow-meaning, if this isn't otherwise obvious.

In addition, temporary development comments help while writing or refactoring code, but they come out and become empty or (a)-(c), eg // XXXX I dont understand this; or # Class is defined in Foo.pm.

Usually code is OVER commented, or the comments are facile eg 'i++; // increment i' and this CRAP should be avoided at all costs.

The other thing to be avoided is lengthy legalese or copyright information spread all over code. If this is necessary, at all, it should fit on one line and if necessary reference a COPYRIGHT or LEGAL file

OK // Copyright (c) 2001-2010 Foo.Bar, all rights reserved, Licenced under the MIT license.

BAD /* Error constants. Linux specific version.

-- 15 lines deleted

      02111-1307 USA. */

Finally, never believe the comments, at minimum they didnt get debugged!

Less verbose is more writeable

[Anonymous Coward]

Early COBOL and Fortran computation code proves you wrong here. COBOL, without COMPUTE, required a separate line for each operation. Fortran from the start showed simple algebraic equations.

COBOL
======
MULTIPLY B BY B GIVING B-SQUARED.
MULTIPLY A BY C GIVING A-C.
MULTIPLY A-C BY 4 GIVING A-C-4.
MULTIPLY A BY 2 GIVING A-2.
SUBTRACT A-C-4 FROM B-SQUARED GIVING DISCR.
CALL SQRT USING DISCR GIVING RT-DISCR.
SUBTRACT B FROM RT-DISCR.
DIVIDE RT-DISCR BY A-2 GIVING ROOT-1.

Fortran
=====
R1 = (-B + SQRT(B**2 - 4*A*C))/(2*A)

Do you want 8 lines of code to write out the quadradic formula? Is that any clearer than one line? A simple one-line comment explains what *root-1* means to the program as a whole.

I've seen people write out intermediate variables like that using PHP or Python. Both languages handle that for you.

Re:Less verbose is more writeable

[zippthorne]

Either way you need commments. Your example code only finds one root, and doesn't handle the case of positive b and abs(ac/b^2) 1 very well. Your comments could explain why you don't expect that case to arise, and why you only need one root.

Or

[MichaelSmith]

The code which is business critical and necessarily complex gets commented a lot as a mitigation measure. But it still has problems, often because the business requirements change a lot or are poorly defined.

compares to all professions

[DaveGod]

Working in accountancy (and doubly-so for audit) a well-commented file is absolutely necessary. Like (I suspect) computer code, the file should stand on it's own - a competent fellow professional should be able to fully understand it and be comfortable reaching the same conclusions. This is not only good practice for the benefit of your firm but a professional requirement: my institute comes along every few years, selects a few files and basically if they have difficulty understanding the file (or worse, reached different conclusions) then you're in a lot of trouble.

Many of the points in TFA hold up well however - explaining things unnecessarily merely adds bloat, irritates and wastes the time of the reader by telling them obvious, patronising or pointless things. And yes, a perfect accounts job doesn't require any explanation because the schedules will be self-explanatory.

The thing is though, if you're doing anything complex (earning your salary), have to make corrections (hackjobs) or judgements then you need explanations. Manager's will be reviewing your work and you or a colleague will be referring to it next year. If explanations go out of date, update them - if they had value before then value is there in updating them. Yes there is a cost, so there is a tradeoff vs their value to the file. The key is competent fellow professional. Assume your colleague will be reviewing your work and be satisfied that they will be able to understand and appreciate it.

If you're just churning out "stuff that works" then you're at best a technician.

Where is your proof?

[SuperKendall]

Well, everyone's welcome to their opinion, but it's pretty well proven after decades of software engineering that code should be commented.

From my decades of software experience across several different languages, there is no such clarity.

Comments are useful, but code is often clear enough by itself. And bad (out of date) comments are absolutely worse than no comments at all as a coder will often trust the comments first.

So while some code should be commented, not all code should be. And that's not really opinion but carefully measured analysis.

If you don't comment your code, I won't pay you for it. I'll inform the management that you neglected an important step and don't deserve a good reference.

Well that's not in the least psychotic.

I comment my code carefully when it needs it, but you are the last person on the planet I would want to work for in case I accidentally cross the invisible line that triggers your Code Rage, and certainly from past experience I know it's bad news to work for people who value procedure about quality and productivity.

Most of what you say is wrong

[petes_PoV]

You presume that the person coming after you will have both your background and your programming ability. This is incorrect. No-one who sees your code will have the same background you have and therefore they will not have the same writing style or familiarity with the problem you were trying to solve. Comments are primarily (but see later) there to save time. They act like signposts on the roadside and should guide people towards an understanding of what a section of code does, why it does it and how it relates to the stuff around it. If your comments don't do this, then you're not a very good programmer. Just like you can drive around and will eventually (as the earth is round) wind up at your destination, having a map, signage and/or a GPS makes getting to the right place a whole lot quicker. Your comments should do the same.

While you are right (as all *experienced* programmers know, anyway) that /* increment the counter */ comments are pointless (but harmless) you've missed an extremely significant type of comments. These are the warning to future programmers why you DIDN'T use the obvious approach, or why a particular algorithm is not suitable for the task in question. Further, code that has been corrected, modified or had bugs fixed MUST have comments to identify that fact. These comments are at least as valuable as the actual code. Again, experience will teach you this.

Finally, never, ever forget the most important rule of commenting. NEVER include a URL in a comment. They change over time and cannot be relied upon to still exist in 3 months, let alone the lifetime of a software product. A similar warning should exist for book / magazine references, too. Not only do they become unobtainable or go out of print, they also get modified or corrected in the "second edition" and therefore still can't be relied on. If an algorithm has a well known name, such as Bresenham's, then by all means quote that otherwise, explain the algorithm in, or before the code that implements it. Unless you want the next guy to curse your name - provided you put that in the comments.

Comments are useful

[trbarry]

There is another myth that says just because something is mathematically unambiguous it also intuitively obvious. And yet the real implications may be lost in the complexity of the situation or problem. Comments can point out anything useful to the code reader.

Also, if you spend enough time staring at a piece of code you can usually figure out what it does. But that does not at all mean you can figure out what the programmer was really trying to do. His/her internt may have been quite different. You can also not figure out all the possibly erroneous assumptions made about the problem space at the time of coding.

Comments form a useful redundancy and sanity check. Being cutely terse in comments is as bad as the clever but incomprehensible code one liner.

You should add comments anywhere you can predict a reader may have a high probability of misunderstanding.

- Tom

Re:Kernighan

[DLG]

This is a point I really am trying to make too... The best code you do, the stuff that required you to actually use your brain hard, is going to be hard for YOU to maintain let alone others. You comment based on your own Eureka moments, you document your understanding, and hopefully it lets a person recognize that you were both solving the problem in a reasonable manner, and that your implementation and solution are in sync.

Beyond that, adding a few lines of code for clarity can also make it easier to debug, to extend and to implement in a different language.

How does this even deserve a /. ?

[upuv]

Because his opinion is against a fairly standard convention he declares himself right and the opposite opinion to be myth.

How arrogant can you get. Really.

"I think MS Windows sucks Donkey Nuggets. Therefore everyone should switch to Android. The power I wield is frightening."

I've been writing code for over 20 years. One thing you learn is that you don't want those "Hey how do you do xyz with method ABC in the code you wrote 10 years ago." calls. How do you avoid this your code follows you like a bad poo cling on. YOU COMMENT YOUR CODE. With descriptions, examples, purpose and anything else that is relevant. You probably should spend as much if not more time on the comments than the code. Cause it will save you heaps of time in the future.

As for documentation that is external to the code? Well it's useless. Because repositories change move and mutate. Over the years the design/requirements/arch docs all seem to vanish. The only thing that seems to live on is the actual code. Why. The code is the business not the power point slide show. The code therefore should also be the documentation.

So Mr. I'm 20something and know everything about writing code. Time to join the real world. I for one never want to have to fix your code.

Re:Kernighan

[azgard]

Thank you, you finally helped me to understand that comic. So it's true after all. You code while intoxicated, and debug sober, when you are smart enough to easily debug your own code. That way you save debugging time, and you get more productive.

Re:Code format

[bingoUV]

Citations:
http://desktoppub.about.com/cs/finetypography/ht/line_length.htm
http://desktoppub.about.com/library/nosearch/bl-linelength.htm

Notice how newspapers break the content into columns, even if a single article covers 5 columns in page width? There is an optimal text width that helps people read best. 80 might be a number coming from punch card days, but it is still a good approximation of "ideal" column width as used by various publishing standards. It is, in fact, a bit more than ideal column width. I see 2 reasons for this:

1. Breaking simple text simply results in excessive hyphenation. Breaking code into multiple lines has higher impact because code has its own indentation too.
2. Indented code that starts at 20th column and ends in 80th column => total width is 60 columns which closer to the ideal columns width.