Are More Comments Better in High-Turnover Environments?

Question

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.

Answer 1

Comments don't clutter the code.

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.

Answer 2

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.

Answer 3

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.

Answer 4

"Are More Comments Better in High-Turnover Environments?"

I think they may well be worse:

• Different authors will use different styles and levels of details and will be less into updating comments by other people.

• The opinion of "What needs commenting" changes from person to person.

• They continue the practice of writing code that is hard to read with comments to explain it as opposed to easy to read code with descriptive names.

• Maintaining their format and consistency becomes a job in itself.

• New users have to learn the 'format' standard before being able to make quick changes.

Answer 5

Point 1: Clarity is important in high-turnover environments

Point 2: Verbosity is not Clarity

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)
• Use a more straight-forward algorithm (conditions permitting)
• Use well-known libraries for common functionality

Answer 6

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.

Answer 7

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.