I was talking with a colleague today. We work on code for two different projects. In my case, I'm the only person working on my code; in her case, multiple people work on the same codebase, including co-op students who come and go fairly regularly (between every 8-12 months). She said that she is liberal with her comments, putting them all over the place. Her reasoning is that it helps her remember where things are and what things do since much of the code wasn't written by her and could be changed by someone other than her. Meanwhile, I try to minimize the comments in my code, putting them in only in places with a unobvious workaround or bug. However, I have a better understanding of my code overall, and have more direct control over it.

My opinion in that comments should be minimal and the code should tell most of the story, but her reasoning makes sense too. Are there any flaws in her reasoning? It may clutter the code but it ultimately could be quite helpful if there are many people working on it in the short- to medium-run.

What do you think will happen when you move on to a different project or a different job and someone else has to maintain your code? Is your code really so clean and clear that someone else will easily understand what you were doing and why?
–
CalebJun 1 '12 at 2:49

2

Lots of good suff in the existing answers. But just wanted to say that if there are now/few unit tests, invest the time in building tests, not comments, for the high turnover environment. If there is time left over for comments, add 'why' comments to both the code and the tests.
–
James YoungmanJun 1 '12 at 3:57

@Caleb Even if it wasn't clean and clear, do you really think smattering comments all over the place would help? Why not just write some documentation elsewhere with descriptions?
–
joshin4coloursJun 1 '12 at 16:35

7 Answers
7

And when they do, well, every half decent IDE can hide / fold comments. Ideally the story should be told by your code, your requirements document, your commit history and your unit tests, and not by comments. However excessive commenting can only hurt when comments are concentrated on the how and not the why, however that's a different discussion.

I think both you and your colleague are "right", the difference being, of course, that you work alone and she in a team, that oftenly includes inexperienced developers. You don't have so much a different philosophy on comments, but vastly different requirements on communicating your code. The "it helps me remember" argument could also stem from the fact that she deals with a lot more code than you, and more importantly code produced by different people, each one with their own personal preferences and quirks.

At the end of the day, code comments, albeit their obvious flaws, are the simplest and quickest way of communicating your code. Depending on team composition and organization, it might even be the only way that applies to the lowest common denominator. I usually find myself following your commenting philosophy when working alone and adjusting to your colleague's when working in a team, especially if it's an unbalanced team skill wise.

+1 on Excessive commenting can only hurt when comments are concentrated on the how and not the why except I would take it one step further and say ANY comments are bad when they explain how instead of why.
–
maple_shaft♦Jun 1 '12 at 2:17

Comments don't clutter the code. Well that depends, especially if you are using #.
–
DynamicJun 3 '12 at 2:08

Prolific comments in that kind of environment are covering up for a problem that should be solved another way.

Quality, readable code should never need additional comments to explain what it does. The only time to comment is when you want to explain why something was done in a particular way. And even then, those comments could arguably be in source control commit messages.

So, the problem she's solving is that she's having to work with students who don't know how to write their code in a readable manner. In my opinion, cluttering the code with comments is a weak solution to that problem.

Stringent code reviews would be much more effective, both in keeping the code tidy and in improving those students for the future, whether that be in the same company or elsewhere.

A thorough code review should question excessive comments by a developer, but you are absolutely correct that her team would benefit much more from regular code reviews than from prolific comments.
–
maple_shaft♦Jun 1 '12 at 2:19

4

"Quality, readable code should never need additional comments to explain what it does." - Which doesn't hold true for 90% of code written.
–
Oliver WeilerJun 1 '12 at 7:46

1

@OliverWeiler: So 90% of code written could do with a good code review. I've had 5 senior developers in a team where all code was reviewed by at least one other senior and they've produced very readable code as a result, with a minimum of commenting.
–
pdrJun 1 '12 at 12:12

1

@pdr For many teams and most applications, assuming a best-case scenario for code quality and readability is a disaster. Everyone thinks their code is perfectly self-explanatory. The truth of the matter is often very different.
–
DaveJun 1 '12 at 13:20

1

@Dave: I'm not suggesting you should assume anything. You verify the quality of the code by giving it to another developer and saying "can you read and understand this?" Which is a much more reliable guideline than "I hope these comments make it readable" and has a faster feedback loop (ie. you can rewrite the code, or add a comment, while it's still fresh in your mind).
–
pdrJun 1 '12 at 13:30

The problem with comments is that they tend to grow out-of-synch with the code really quickly. This means there are often misleading or flat-out wrong comments in the code, so they hurt readability more than they help.

The goal is to make a codebase easy to understand and modify. You can do this though liberal use of comments (though you might run into the problem out of data comments), or you can write self-documenting code (as much as possible), and only use comments to explain the non-trivial "why" questions. Either approach might work, but keep in my that to modify the code you will have to understand the code itself, and not just the comments. So while comments might help you understand the code, at the end of the day you will still probably have to understand the code itself. With that said, I prefer the self-documenting code approach. It seems to be a more direct way to create a clean codebase.

The issues you list are also issues for the code itself in a high turnover environment, not just the comments. That's... interesting ;) More of a people problem, than a code / comments problem.
–
Yannis Rizos♦Jun 1 '12 at 10:56

+1 Hi Yannis, yes that's a very good point. I agree. I also think that because code itself is a little more structured - has fixed names for certain things, simplest example - a function "to_string" has no ambiguity, must be called that, where as comments have absolutely zero structure or agreed upon terms kinda thing, that makes comments troublesome. Then again code can end up with a lot more 'spaghetti' then comments. Interesting.
–
Michael DurrantJun 1 '12 at 13:00

Adding comments to your code may or may not improve the clarity; it depends on the comments you add. And once optimal clarity is reached, additional comments will make the situation worse, not better.

While comments are a component of clarity, code quality is a significantly more important component. Cleverness is the opposite of clarity. If the function of the code isn't immediately apparent through a casual reading, then the code isn't particularly clear, and comments (no matter how high-quality the comments are) are a poor and ineffective substitute for clear code.

For example, stuffing a flag in the high-bit of an unrelated field may be perfectly allowable in certain circumstances, and it may make loads of sense from a performance perspective in certain circumstances, but it's pretty much always a bad idea with respect to clarity, even if you comment the hell out of it.

If you find yourself having to explain in prose what your code does, then consider any of the following: Note that some of these may affect performance, but performance may not be as important as clarity in certain cases.

Better variable names and function names

Better code layout and spacing

Remove any "tricks" that you thought were a good idea

Group code according to conceptual function (e.g. extract code for a specific purpose into an appropriately-named function, even if you only call it once)

An oversimplified answer: "The more likely your code is to be reread, the higher the burden of explaining what you are doing." This could be by making the code easier to read, by commenting it, by creating formal documentation, by following style standards... Please note that it could be you that is doing the rereading later, though it's certainly also true of others in a high turnover environment.

There is another great thread which covers whether or not comments are documentation.

Comments are more helpful in some scenarios than others. This is so fundamental that I worry about how to explain it in the midst of so many answers that I perceive to be "anti-comment".

If your code might not be read for years, comments are more important than if you have frequent code refactoring, strong code ownership, and copious code reviews. If your application is complex and uses techniques that are not immediately obvious to an observer proficient in that language, comments are more important than if the system is a glorified "Hello World." If the code base isn't as strict with standards as it could be, comments are more important than if you're working with six layers of QA. If you're working on a team with eight people just learning the language, comments are more important than if your team has eight programming Pulitzers. If you got a sprawling application dropped in your lap, comments are more important than if you were able to build it clean from scratch.

Would it be better in most of those scenarios to fix the underlying cause instead of increase the use of comments? Absolutely. But sometimes you're stuck with a code base that has more fingerprints on it than the town smartphone, and the best way to improve it is to make your changes as readable as possible and comment the heck out of it.

To your specific problem: comments shouldn't be strewn about so much as to clutter the code. A well-written paragraph at the top of a subroutine, describing why a function exists and maybe why it uses that approach, is often the best bet to help the next programmer get their bearings.