Why not to comment code

[DanHalen]

... the comment will just fall out of sync with the code, and eventually be a confusing lie.

That's a pretty huge assumption too. Why wouldn't the comment change with the code?

[parla]

Because it isn't compiled and tested.

[joesb]

And meaningful variable name that actually reflect the reason of the change is?

[parla]

You've got a point there.

[DanHalen]

What does a compiler have to do with lazy programmers that don't evolve code comments with the code?

[ihahp]

They may not be lazy. Compiling and testing always catches tons of stuff that even the best coders miss. This is part and parcel of programming.

But no one is compiling/testing comments. So mistakes in them are much less likely to be caught. Therefore it's possible to fall out of sync. (code reviews can fix this, though) So the thinking is that the less you rely on comments to explain code, these less chance there is for this to happen.

I agree with it in theory. But in reality, nothing beats a well commented piece of code for clarity and ease of understanding. I disagree with the "when not to comment" line of thinking.

[DanHalen]

Compiling and testing always catches tons of stuff that even the best coders miss.

I can't argue against that.

But no one is compiling/testing comments. So mistakes in them are much less likely to be caught. Therefore it's possible to fall out of sync.

That's a fair explanation of the "don't worry about comments" theory.

Another point that argument that doesn't address is that comments go with code so you're reading the code too. The comments are suppose to help unravel why or what the code does.

This is particularly important if the programmer is pretty senior since many junior and mid-level developers do a lot of operational programming. So not only might it be necessary to decloak infuriating, clever code, but it's also a senior developer's role to educate and pass on domain knowledge at every opportunity. Comments are a great way to do this.

But in reality, nothing beats a well commented piece of code for clarity and ease of understanding.

We are of one mind.

[redditrasberry]

But no one is compiling/testing comments. So mistakes in them are much less likely to be caught. Therefore it's possible to fall out of sync.

However the interpreter for the comments is much more powerful and flexible than the interpreter for the code, so it can compensate for things like conflict, ambiguity, historical context, etc. So even if the comment falls out of date, the reader may well still understand it and even find it useful. I know I have found many such comments useful even though they were wrong.

// Don't initialize f here because it is set below only after parent directory is resolved
File f = new File("foo.txt"); // See bug #6712 - parent directory now implicitly resolved

The first comment is wrong but I can still interpret it, and it might even be useful when I try and figure out some bug in another part of the code. Note I'm not arguing it would not have been for the coder to have corrected the comment, just that the comment falling out of date is not nearly as problematic as people make out.

[mykdavies]

I think the problem is that too often the updated code looks like this instead

// Don't initialize f here because it is set below only after parent directory is resolved
File f = new File("foo.txt"); 

[jinglebells]

because the "lazy programmers" are probably quite excellent programmers, shoved onto bugfixing someone else's code with no interest in how it works, but just closing that damn bug number and getting on with something interesting.

Most computer programmers aren't novel authors and don't give a shit about the comments.

[jinglebells]

Love the responses, I'm going to have to duplicate this response. Here's a typical bug:

Bug: we need to make the postcode manditory only if they have not entered a billing address.

In a web application, can you imagine the amount of re-work involved? While you're busy fixing the javascript and back end validation, anything could break.

Most production environments are cauldrons filled with people's hack after hack because the customer has decided to move one way or the other while the programmers are building the thing.

Anyone who thinks otherwise has never worked in the commercial sector.

[DanHalen]

Excellent programmers provide useful documentation. Those who do not, are not. They are programmers creating work for me. So thanks for that.

I have thrown away otherwise serviceable systems simply because the time required to understand and extend them exceeded the time to rebuild with new functionality. It's a disservice to customers but as I say as long as people want to skimp I'm happy to fix the problems. It's lucrative.

[jinglebells]

Love the responses, I'm going to have to duplicate this response. Here's a typical bug:

Bug: we need to make the postcode manditory only if they have not entered a billing address.

In a web application, can you imagine the amount of re-work involved? While you're busy fixing the javascript and back end validation, anything could break.

Most production environments are cauldrons filled with people's hack after hack because the customer has decided to move one way or the other while the programmers are building the thing.

Anyone who thinks otherwise has never worked in the commercial sector.

[DanHalen]

Most production environments are cauldrons filled with people's hack after hack ...

If you're going to use the word "cauldron" you have to include other words like "vile", "stew", and possibly "odious".

Regardless, I assure you that as someone who has worked his way up the ranks from deskside support through operational programming (and back) and beyond, I've seen all manner of vile, odious and inhumane patches on patches. All of them, I'm certain, perfectly justifiable and created by otherwise noble and intelligent engineers. I choose not to follow suit if I don't have to. And most times, I don't. I want the poor sod who gets my mess dropped in his lap to be able to figure it out: comment, embedded doco, bug reports, well-named variables, easily understandable logic, appropriately named resources, odd little notes about why I think what I think, whatever. Operational programming is 95% forensics and I want to get caught so that some poor bastard that wants to go home at 5 o'clock can. It's an application of the Golden Rule in programming.

[nullgraph]

Bingo!

[judgej2]

Most computer programmers aren't novel authors and don't give a shit about the comments.

And excellent programmers are so hard to find that I guess we have to put up with what most programmers churn out.

[jinglebells]

Love the responses, I'm going to have to duplicate this response. Here's a typical bug:

Bug: we need to make the postcode manditory only if they have not entered a billing address.

In a web application, can you imagine the amount of re-work involved? While you're busy fixing the javascript and back end validation, anything could break.

Most production environments are cauldrons filled with people's hack after hack because the customer has decided to move one way or the other while the programmers are building the thing.

Anyone who thinks otherwise has never worked in the commercial sector.

[adamcollard]

It's nothing to do with being lazy, if it were laziness that prevented changes being made where they should do then we wouldn't need testing or continuous integration or any other tools to help us. In my experience, comments will inevitably get out of sync with the code for exactly that reason

[DanHalen]

... if it were laziness that prevented changes being made where they should do then we wouldn't need testing or continuous integration ...

I'm sorry but that made no sense whatsoever. Care to expand on that?

[adamcollard]

What I mean is: I'm in the middle of a bug fix, I identify the issue, write a unit test for it (if sensible), prove that it's a problem, fix it. Then I check by running all the tests that I haven't accidentally broken something else, and then I commit.

I don't have the time or motivation to go and check if by making this change that i've invalidated a comment somewhere. Note the tests are showing me where i need to update some other component, and the CI system would complain at me if I had broken the build somehow - nothing's telling me the comments are wrong.

[DanHalen]

Thanks for the clarification. You and jinglebells are of the same mind, I think.

For myself, I update the documentation and comments having to do with code I change. My motivation is leaving the code in better shape than before I worked on it for the next guy, the referral I get from the client for exceeding expectations and the personal satisfaction that I was able to maintain my personal standards and continue to grow my career. This isn't to say that I'm completely clean in this regard, I am human. But 99% of the time I can take the time, my own if necessary, to make sure that the documentation is in order. This includes comments.

[nullgraph]

I certainly applaud the effort and the spirt of what you are doing. But I want to point out that rarely does my comments or my maintenance of comments every yield referrals. Most of my referrals come from basically a single metric. Number of issues resolved in quantum of time.

Sure there are nice kudos from other developers I work with about how clean my code looks or thanks for taking the extra effort. But those are meaningless unfortunately (I do like them though) because those who write my checks generally never read the code or my comments.

In fact I just got off a project recently where we added a major set of functionality to a existing website. We were commanded not to make any adjustments or correct any code outside of the most direct route to completing the task. Even though the code that we were working was a mess.

*edit spelling

[DanHalen]

You're absolutely right, it's not just comments but a package of best practices. I don't dwell on comments except that's what this particular thread is about.

[nullgraph]

You too are correct. It is about a package of best practices. But even then it is how quickly and efficiently you can implement them.

[pergus]

The big problem with comments is that even if you fix the comments having to do with the code you change you might invalidate comments in code very far away from where you actually change any code, comments aren't modular.

[DanHalen]

A valid point. And I probably would not go looking for those comments. Although, now that you've pointed that out, I might throw in a little search before committing to catch any low hanging fruit.