One of my team members consistently avoids making comments in his code.

His code is not self-documenting and other programmers have a difficult time understanding his code.

I have asked him several times to comment his code, however he just gives excuses or claims that he will do it later. His concern is that adding comments will take too much time and delay the projects.

What argument can I present to convince him to properly document his code?

On that note, am I wrong to focus on the code comments or is this indicative of a larger problem which should be addressed?

It's the end, not the means

Comments alone don't make for better code, and just pushing for "more comments" is likely to give you little more than /* increment i by 1 */ style comments.

So ask yourself why you want those comments. "It's best practice" does not count as an argument unless you understand why.

Now, the most striking reason for using comments is so that the code is easier to understand, and when people complain about a lack of comments, they are either clueless parrots, or they have a hard time understanding the code they're working with.

So don't complain about missing comments: complain about unreadable code. Or better yet, don't complain, just keep asking questions about the code. For anything you don't understand, ask the person who wrote it. You should be doing that anyway; with unreadable code, you'll just ask more questions. And if you come back to a piece of code later, and you are unsure you remember correctly what it does, ask the same question again.

If comments can fix it, and your colleague has a functioning brain, he/she will at some point realize that commenting the code is much easier than having you around asking stupid questions all the time. And if you can't come up with questions, then maybe that code is perfectly readable already, and it's you who is at fault—after all, not all code needs comments.

On the people skills front, avoid sounding condescending or accusing at all cost; be serious and honest about your questions.

Nagging won't help

I have met lots of devs who've had trouble writing self-documenting code or helpful comments. Those kind of people most often just lack enough self-discipline or experience to do it right.

What never works is just "telling them to add more comments"—this will increase neither their self-discipline, nor their experience. IMHO, the only thing that does work are frequent code-review/refactoring sessions. Whenever the dev has completed a task, go with him through his code, and let him explain any function or code piece you don't understand. Immediately refactor or document the code in a way so that the two of you will understand it 6 months later.

Do this at least some months, and if you are lucky the other devs will learn enough from those sessions that you can reduce the review frequency.

Depends on what your roles are

First of all, I would suggest you re-address your approach about the comments.

If they are documentation comments at the API level (exposed later to the public), then this developer simply isn't doing his job. But for all other comments, be careful.

In most of the cases I encounter them, comments are evil. I would recommend reading the code comments chapter of "Clean Code" by Robert Martin to get a good understanding why.

Comments hurt your code in several ways:

They are hard to maintain. You'll have to put in extra work when refactoring; if you change the logic described in the comment, you need to edit the comment too.

They often lie. You cannot trust comments and must read the code instead. Which raises the question: why would you need the comments at all?// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
//the calculation of the hash
int result = a*b;
}(The hash is not the sum but the product.)

Comments clutter the code, and very rarely add any value.

My solution: Instead of adding more comments, try to get rid of them at all!

Find the original post here. See more Q&A like this at Programmers, a site for conceptual programming questions at Stack Exchange. And of course, feel free to ask your own.

Promoted Comments

Hah, what has always fascinated me about this question is how irrational and defensive developers get about it. *All* of the answers so far focus on the reasons to use or not use comments; not one deals with the actual question which is essentially orthogonal: in an environment where comments are expected, how can you induct someone new who does not write comments?

Looking at the way people respond to the question, the answer might be as simple as this: you can't. Lots of developers are fundamentally dogmatic about this.

For instance: tdammers says at the end of his post to avoid being condescending or accusing. Good advice. Yet earlier in his post he claims that people who complain about a lack of comments are 'clueless parrots' or that they have a 'hard time understanding the code they are working with'. Huh. This isn't a rational position to take: implying that there is something deficient about those who take issue with your argument is an ad-hominem attack, a very weak rhetorical technique. The 'clueless parrots', if they exist (and they probably don't) can't be just copying each other: there must be someone with whom the opinion originated, and there's no shame in having difficulty understanding poor code.

There are further examples of this in the comments above (I myself have been accused in the past for being 'childish' for taking the position that comments are often a good thing). It's an interesting phenomenon, and I think addressing it is probably key to answering the original question.

Hm. The first issue appears to be one of bullying: developers who do not write comments call their colleagues 'parrots', 'morons', 'childish', make unsupported claims of 'bad code smells', etc. That's clearly not something that generates a healthy environment, and someone who has previously worked for such people would probably be quite reticent about writing comments. This can probably be addressed by creating a more positive environment: pairing the new developer up with someone more experienced in the way things are done - in particular, who understands *why* they are done the way they are - will probably be all that's required.

There's a flip side here: they might have been one of the bullies. You probably don't want someone on your team who thinks of their teammates in these terms: if they can't change their attitude, you must let them go. Your team will fall apart if you don't.

The next issue is that some good developers aren't also good communicators. Comments are all about communication, so this can cause a problem. How you deal with this depends on the precise situation. It's possible that it's simply a matter of confidence, in which case all that needs to be done is to persuade them to try, and then make sure that everyone is constructive if the standard falls short. It's possible that there's something more fundamental, and your developer is never going to be good at writing comments (a dyslexic developer, for instance, will always have difficulties in this area). Give them support in this case: if the rule is unbreakable, then you can always fix the comments up in a code review. If it's flexible, you also have the option of adapting as a team to your developer's coding style.

Finally, the developer simply might not see the value in comments. If your coding guidelines are presented as a list of rules without explanation, it's easy to see how someone new to the style might not instantly comprehend why those rules were laid down. Change how the guidelines are presented: explain what effects they are intended to produce and why they are written the way they are. This is in fact also the argument for writing code comments in the first place, and it gives your developer the capability to judge for themselves when a particular guideline may not apply.