How to convince people to comment their code [closed]

https://stackoverflow.com/questions/159597

03-07-2019
|

Question

What are good arguments to convince others to comment their code?

I notice many programmers favor the perceived speed of writing code without comments over leaving some documentation for themselves and others. When I try to convince them I get to hear half baked stuff like "the method/class name should say what it does" etc. What would you say to them to change their minds?

If you are against commenting, you please just leave comments. This should be a resource for people trying to convince people to comment the code, not otherwise. :-)

Other related questions are: Commenting code, Do you comment your code and How would you like your comments.

Solution

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.

OTHER TIPS

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.

Write your code well.
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.

Explain what you're doing. Your code quality should do most of this work for you though.
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.

I'm not being snarky at you, but you should rephrase the question to be How do you convince other developers to work as a team?

Seriously, some people assume you can read their mind.

If you're part of an agile team, code is collectively owned, so when you see uncommented, awkward, or hard to read code, go ahead and change (refactor) it so you understand it. If people complain, tell them why and be upfront. That you found it incomprehensible, and nobody owns the code.

Our strategy is to have systematic code reviews, and to reject code that's not properly documented (through comments, proper function naming and organisation, etc...). If it's not clear to the reviewer, you go back to the work bench, period.

I would say "yesterday I had to read some of your code. I was able to understand it but less than or equal to 5 well-chosen lines of commentary explaining how it accomplished its goals would've allowed me to read it in about one-tenth the time and then I could've worried about understanding a problem instead. I'm not stupid, and you're not smarter because you can write things that are difficult to understand. On the contrary, if you can't produce readable documentation+code ensembles then you're less of a developer."

I had this drilled into me long ago: if you write something and someone of reasonable ability can't understand it, then it's your fault, not his or her fault. This applies to writing in natural languages, and it applies to writing in programming languages.

There have been similar discussions about commenting. Here's the one on what rules people follow when commenting code: What are your "hard rules" about commenting your code?. Some of the answers have also very good reasons why you would want to comment your code.

Show wisdom in your desire for comments, and they will be more likely to listen.

Less is more.

Emphasize quality over quantity.

In my team, there was a push to comment everything in certain API's. Some developers began using a tool that would automatically generate comments by looking at the method names and signatures.

For example:

/// <summary>
/// Gets the Person.
/// </summary>
/// <returns>
/// A Person
/// </returns>
public Person GetPerson()
{

}

Can you think of a bigger waste of screen real estate? Can you think of a bigger waste of brain cycles than reading comments that provide no new information?

If it is obvious from the method signature, don't say it! If I can figure it out in a few seconds, don't put it in a comment. As others have put it, tell me why you chose to do it that way, not what you did. Write your code so that it is obvious what it does.

Lead by example. Developers are easily swayed when they see The Right Thing, so seeing solid practices in action may encourage them to do the same. Additionally, you could encourage your group to adopt code metrics that address code maintainability and comments. For example, Code Analysis will produce a bug for methods without summary documentation.

The current coding standards at my current place of work is to comment every function. Blanked rules like this are harmful, and should never be in place. There are situations (and some of them common) where adding comments removes readability.

class User {
    getUserName() { /* code here */ }
}

What is the point in adding a function header to the above peice of code? What else are you going to say besdies "gets the username". Not all code needs to be commented. My rule of thumb is: skip the comments if you are not adding any useful information that the function signature does not.

Comments should be thorough, written at the level of intent (why not how), and rare.

When writing code I tend to comment reasonably heavily as a matter of course. Then, I go back through and try to delete as many comments as possible, without decreasing the understandability of the code. >80% of the time this is as easy as extracting a well named method, this usually results in a comment which merely duplicates the information in the code itself. Beyond that, if there's a section of code that "needs" a comment I look for ways to simplify it or make it clearer.

Code should be self-documenting, and with the right techniques you can get 95% of the way there pretty easily. Generally I consider it to be a failure if there are any comments remaining on code that I check in.

Depends on how much power you have...

I found a very effective way was to make it a fixed part of peer based code reviews - points for comments. If there was a remark that the code was badly commented I would make the developer comment it to my satisfaction, which basically meanth they had to describe enough of the code for me to understand it by printing it out and reading it. And I would do it too.

Remarkably this was popular with the developers, even though it sounds dickensian. Two things happened. First, people started to comment their code. Second, badly commented code became a sign that the developer didn't quite understand what they had written (otherwise they would have described it).

The only real downside was that the comments had to be kept up with the code when it was revised for bug-fixes etc. This was almost impossible to enforce in a real development shop, but once enough good practice was engrained it sort of happened naturally.

BTW I prefer comments in the code itself rather than a Dostoevsky novel as a doc string. The former is a useful aid to subsequent programmers. The latter is just a long piece of out of date text that fills up the docs and misleads everyone.

Have them use an unfamiliar API, but do the programming on a non-Internet connected machine(if you can find them these days) so that they don't have any access to the API documentation. This is effectively what they are forcing other developers to do if they are trying to use the code of the non-documenters!

You also have to differentiate two different comments here:

API comments (javadoc or other similar kind of documentation): you can ask for them to use their own code in a limit scenario (boundary conditions like null objects or empty strings or...) and see if they actually manage to remember what does their own functions in those case
(That is why I am for a complete javadoc including limit-value)
Internal comments (within the source code): you can ask them to explain any function they have coded, just pick a function with a really high cyclomatic complexity level, and see them struggle around all the different code workflows and decision branching ;)

Well, there's always the "if you don't comment your code, we'll find someone else who'll comment theirs" approach.

More gently, tell them that they are sorely letting down the team if they don't document and comment what they are doing. The code does NOT belong to the individual, unless they are complete lone wolves. It belongs to the team, the group, whether that be a company or a community.

"Writing Code" = "Writing sequence of commands in a special language" + "Writing comments"

It shall be self-evident to comment code while writing it! Have you ever commented code that is already 3 or 4 months old? (Of course you have, and it was everything else but fun!)

If your project is already well documented, programmers who add new code may be motivated to write comments in a similar manner.

@James Curran I 100% agree! I can read your code and figure out what you told the compiler to do; but that doesn't mean it was your intent to make the compiler do that. I know I'm not an arrogent enough programmer to believe that everytime I write code it does exactly what I was trying to make it do. Additionally, I often find it helps me catch silly logic errors in my code by going through after I've written it and trying to explain what I intended for the code to do.

One idea is to point out that it takes less than a minute to write one or two sentences per class and less than half a minute to write one sentence per method.

Tell them to document their functions and interfaces with Javadoc commments and then to run the code through Doxygen to generate cool-looking HTML documentation for their code. The coolness factor can be a good motivator sometimes.

I use one subtle technique:

I set the level of warnings in the project to be reported as errors. And our Continuous Integration server is building the whole solution along with XML documentation upon each ckeck-in.

If developers do not write the comments, the build fails! And after that, they have to write the comments, so after a while, they got used to it.

It isn't aggressive in terms of pressure, but i find it like nice way to correct their behavior.

If developers have to take part in code reviews and are exposed to good commenting they should be able to get the clue. If they do not see the practice as useful then they should get some feedback from their peer reviewers.

Failing that (assuming you're the supervisor / manager) make it part of their performance appraisal. If you can measure it, you can appraise based on it.

Ensure that it's a REVIEWED commenting that you score on, as the passive-aggressive devs will document every last statement as a not-so-subtle FU.

I've become a firm believer in what I call Headrick's Rule, named for a coworker of mine who discovered that a good way to motivate someone to do something is to make it painful for them not to do it.

In your case, asking your non-commenting developers to spend an hour or two explaining their code, perhaps to a "slow" audience, perhaps during their lunch hour "to avoid project slippage" will go a long way. Smart people--even stubborn ones--learn fast!

In my opinion (and I'm talking about .Net programming here) if you have to put a comment you have failed in making the code readable. The answer is usually refactor!

However, if you feel you have to put a comment then it should always be a "why" type of comment and not a comment that explains what the code does.

Writing down what a method / class will do before actually coding it helps a lot to get it right - and you have commented it.

Only employ good engineers who ensure their code implicitly states the intention (using comments and otherwise). Anyone who wants a job will have to do it right. Harsh, but fair, IMHO.

Licensed under: CC-BY-SA with attribution

Not affiliated with StackOverflow