What to do with a person who does not comment on the code?

Question

Programming

Friday is such a question. There is a talented developer who does not document the code, or does it in very small quantities, because "I do not have time for this" and "everything is clear from the code." For a number of reasons, administrative measures cannot be applied to him. But there is a desire to find such arguments to persuade this person to document his code. I will study your suggestions with pleasure.
upd 09.10.2011 Thank you all for your advice! A code commit hook would be ideal, I will work on such a solution. At this stage, my Wishlist does not go beyond a brief description of the class / methods, comments “inside” the code suit me.

Answer 1

If the code is really clear, then why force you to write too much? If the code is incomprehensible in some places , reasonably demand to comment on such places. As arguments, it is desirable to cite the fact that the code is incomprehensible to other developers (that is, you need to ask several people to explain what the code they do not know does in 5-10 minutes).
If I understood correctly, then in your case the person is "special" in some senses. In particular, it cannot be forced to do what you want. Therefore, here you should try to convince a person or, as an extreme option, come to a compromise.
As a developer, I can say that I myself am an opponent of comments, but with a caveat: obscure moments still need to be commented if it is not possible to rewrite. Another thing is that when management or colleagues begin to push through the desire to see comments everywhere, this causes irritation, since it’s harder to live with comments (I won’t “button” about the fact that they are not easy to support, etc.)

Answer 2

Hook him up more often on every little thing and several times if the lack of documentation creates difficulties for you, so that he understands that it is better to describe once than to explain 10 times. Call Saturday night, 5 am, lunch time, etc.
The main thing is not to overdo it, so that, if it is his power, the idea does not arise to dismiss / replace with a less curious employee.
Well, if the lack of comments does not affect your work in any way, then, of course, understand and forgive. Some developers don't comment on the code, believing they have it, and since the Dumais novel is written, sometimes some of them are right. And few people like to document like this without a kick at all

Answer 3

Give him code without documentation for revision + support. Let him feel the usefulness of comments in his own skin.

Answer 4

To begin with, show how he writes and the places of the code that he comments on himself, and maybe everything is clear to everyone in truth +)

Answer 5

The code should be clear without comments.
It is necessary to write comments only where it is impossible without it (non-obvious solutions, complex algorithms)

Answer 6

Monitor his code for a week and count all the times the code caused problems. Also count the time spent explaining and causing downtime. convert to money and present him the calculation. Like, if I had spent a minute on a comment here, then here we would not have lost 5,000 rubles and 2 hours of time. You supposedly bring losses by not commenting the code.
When he sees real losses, he (maybe) will be imbued. If not imbued, then to the higher.

Answer 7

Talk to him and the team about how interested you are in the final product.
If the product is ordered, and the order requires documentation (you know, such ... on hard, rustling media, or translated into them), then he should have a direct interest in using /** javadoc */ comments to generate documentation.
If your product and your team continue to support it, then try to convey to him that in the end it will be better for everyone after 2-3 years of development and fouling of the project with new chips. Define a minimum, for example, /** javadoc */ to the class and methods + separate comments in the twisted code.

Answer 8

Or maybe NOT write comments - is this age? I didn’t write them myself before, but once I read a wonderful phrase:
“Programs are written for people, not for computers.”
Since then I have been writing them. The code, of course, should be clear without comments, but you can learn from well-documented code. You never know who the code will fall into the hands of, but the other person will say thank you.

Answer 9

He is right in his own way. If you write normally, then in most cases everything is really clear from the code. And comments only take up space, and even over time they begin to mislead people who read them if they parted with the code. But if this is part of the corporate culture, then simply do not accept the pool request without comments, that's all. Either he will start writing comments, or he will not make features and will fly out "for poor progress", then it's up to him to decide.