How to convince people to comment their code [closed]

Question

Only comment the "why" and not the "what". In so far i agree, it should be clear from the class or method or variable name what it does and what it is used for. Refactor where it doesn't instead of commenting it.

If you take this approach, you will get comments, and you will get useful comments. Programmers like to explain why they are doing something.

Show them their own code from 6 months ago. If they can't understand and outline exactly what it does within 2 to 4 minutes, your point has probably been made.

My opinion:

I wouldn't. The method/class name should say what it does. If it doesn't, either the method or class is trying to do too much, or it's named poorly.

I'm a fan of commenting why, not what. If it's not clear why code is using one approach over another, comment it. If you had to add a hack unused variable to get around a compiler bug, comment why. But comments like "//Connect to database" are signs of bad code or bad policies. A method named ConnectToDatabase() is much better. And if it has "//Determine DB server IP" in it, perhaps that should be pulled out to a method named "DetermineDbServerIPAddress()".

Design can be documented, but comments are a generally a poor place for that level of documentation. With knowledge of the design, and some comments on why, the what and how should be obvious. If it's not, rather than convincing them to comment their code, get them to improve it.

Perhaps it's just something that has to be learned from experience; specifically, the experience of coming back to your own code after six months, and trying to work out what the hell you were thinking (or what you were on) when you wrote it. That certainly convinced me that comments weren't such a bad idea.

Give them some (~500 lines, minimum) horrible, uncommented spaghetti-code to refactor. Make sure variables are not logically named. Whitespace optional.

And see how they like it!

Overly harsh, but it gets two points across in one go.

1. Write your code well.
2. Comment it so you and others know what it means.

I should stress that this code should not have originated from them. Comments are really useful for understanding your own code, months down the line, but they're also nigh-on essential for understanding complex parts of other people's code. They need to understand that somebody else might have to understand what they're doing.

One final edit: Comment quality is also pretty important. Some developers have an almost 2:1 code-to-comment ratio in their work but that doesn't make them good comments. You can have surprisingly few comments in your code and still have it make a lot of sense.

1. Explain what you're doing. Your code quality should do most of this work for you though.
2. More importantly, explain why you're doing something! I've seen so much code that says exactly what something is doing with no real idea why the developer (unfortunately me most of the time) thought it was a good idea in the first place.

Remind them that reading the code can only tell them what the code does, not what it is supposed to do.

If you or the other developers have not read Code Complete (or Code Complete 2) yet then stop what you are doing and read it.

One thing that standands out is "A function should do just one thing and do it well". when such a function is named after the one thing it does well what further need is there for comment?

Comments have the habit of going out of sync with the code they're supposed to be describing. The result can be worse than not having the original comment in the first place. Not only that but developers know that comments can age and can't be trusted. Hence they will read the code and discern for themselves what it is actually doing anyway! This kinda nullifies the point of putting the comments there in the first place.

Having said that the same can be true of a function name, it may have been well named originaly but overtime new operations have been added to it that are not alluded to in the name.

All comments seem to do separate out the lines of code a developer would prefer to be closer together so that they can see more per screenfull. I know my own re-action to a piece of code with lots of comments that I've got to understand. Delete all the comments. There now I can see what the code is upto.

At the end of the day if your going to spend time making things right your time is far better spent refactoring the code to ensure its as reasonablly self-describing as it can be rather than just writing comments. Such an excercise pays off in other ways such as identifing common chunks of code.

Its worth bearing in mind also that many good developers much prefer writing crisp clean C#, Java, whatever than the far less precise human languages with all the assumptions and ambiguities that they have. True most people with common sense would know how much detail is enough detail but good developers are not 'most people'. Thats why we end up with comments like \\adds a to b and store it in c (ok thats too extreme but you get the point).

Asking them to do something they hate doing and are frankly not very good at (even if you're convinced its the right thing to do) is simply a battle already lost.