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 him 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?
Best Answer
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 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.