documentation - How to convince people to comment their code

Question

question from:https://stackoverflow.com/questions/159597/how-to-convince-people-to-comment-their-code

Answer 1

The best way to convince a person is to make them realize it on their own. Make them debug well commented code. It will show them what good commenting looks like - comments are no use unless they really convey relevant information (which is usually the "why", because the code describes the "what"). They will notice how easy it is. Then let them get back to some of their old code. They will notice how hard it is. You have not only shown them what not to do, but what to do (this is more important). You don't have to do any more. What's more, you don't have to try and convince them verbally. They simply must understand the need to comment code in their own way. This is of course, assuming that the code that needs to be commented is not self explanatory.