How do I convince my fellow devs to WANT to add comments to source code commits?

Question

I know that Subversion (what we're using at work) can be configured to require comments on commits, however I'm not in a position of power to simply turn this on. I know that my reason for commenting my commits is because it is useful, if only as a memory-jogger, to quickly understand the reason behind the commit. However, this doesn't seem to be enough to combat the two responses I always get:

1. It takes too long and I just want to get my changes into the repo.
2. It's easy enough to just look at the diffs.

I even show them the value of simply putting in a JIRA issue ID and how it automatically gets tied to the issue, but still no dice with them.

Worst of all, the person who can make the call is in the same camp: doesn't want to bother and is fine with looking at diffs.

I know it's the right thing to do, but how can I make them see the light? Even if I can't convince my fellow devs, how can I convince management that it's the right thing to do for the business?

Answer 1

Focus on "Why". Its all very well looking at the diffs and seeing that someone changed the logical flow of a section of code or something like that, but why did they change it? The why is usually in the associated ticket (JIRA for you).

They may wonder why the "Why" is important but in 2 years time when you have caught some bug that is a knock on effect of that change, knowing why it was done is incredibly important for not only fixing your new bug, but making sure you don't cause the old bug to re-emerge.

There is also the auditing reason. Binding commits and ticket id's make it really easy to say ok, we're pushing out Version 2, this fixes defect 23, 25, 26 and 27 but there are no commits against defect 24 so it is still outstanding.

Answer 2

Make them do the merges and deal with support. Again maybe you are not in a position to to do this, but if you find yourself being the one to troubleshoot a problem from a previous commit politely send it over the fence and say. I can't tell what you did because there are no commit comments, you made these changes you need to figure it out.

Also for merging branches. Not sure if that falls on you or not, but that is one area I found comments useful.

Again, not in your boat, but when I managed a software team I told them if they made good commit comments I would use those in liou of a weekly status report. Got excellent commits after that one and it was easier for me to keep track of what was going on as the manager as well.

Answer 3

We need check-in comments for the same reason we need line breaks and spacing in our code. To make things easier to track down, understand read and comprehend.

Sometimes you need to diff compare, but often you do not. Forcing devs to diff compare when all they needed was to read 2-3 sentences is a total waste of time. I wonder why they don't see the value of developer time.

Answer 4

• Set a good example. Make your own commit messages a shining example of usefulness. Include references to whatever other systems your team uses for managing stories and defects. Put a brief statement summarizing the change, and a good explanation of why the change is necessary and not something else in every submission.
• Whenever the lack of a decent commit message causes you extra work, throw a question to the submitter. Be persistent with this (but not a jerk).
• If it's not overstepping your role, write a script that sends a daily changelog using the commit messages. This will lend credibility to your argument that useful messages have a benefit beyond browsing through revisions. This might also help get management on your side, since they'll see day-by-day what's happening.
• Identify your allies. Hopefully there's at least one other individual who agrees with you (perhaps by silently not disagreeing). Find that person or those people and convince them further so that you aren't standing alone.
• When the opportunity to mention how decent commit messages have saved you time (or poor messages have cost you time) presents itself, seize it.

Don't be afraid to be the squeaky wheel. Fighting other peoples' bad habits is often a war of attrition.

Answer 5

This has to be one of the most bizarre questions I've heard. People spend hours or even days fixing something and an extra 2 seconds to type in a commit message is too long?! I have to say I would worry about working with such short-sighted people. They are obviously not using their tools to even close to their full potential.

Here's an example from a code review I was involved in last week. Our version control software doesn't preserve history across merges, so for older changes you have to find the exact branch it was made in, otherwise the commit message just shows something like "merged from branch Y." Branch Y might show "merged from branch Z," and a branch a few levels of nesting deeper actually has the real commit message.

A new employee didn't know how to track down the history correctly, which means he was essentially working with just the diffs. He saw some commented out code related to the bug he was tracking down. When he uncommented the code, his bug went away. He assumed someone had commented out the code during debugging and mistakenly checked it in.

That didn't feel right to a couple of us during the code review, so I tracked down the real commit message and found there was a valid reason for removing that code a year ago. The new employee was able to fix his code to fix the newly discovered bug without reintroducing the old one.

There are better ways to avoid introducing those kinds of regressions, like thorough unit tests, but somehow I don't see people who can't bother with a 2-second commit message "wasting" time on unit testing.

Answer 6

I had exactly the same problem here, so I added a pre-commit hook to Subversion so it wouldn't accept any commits that didn't start with User Story number (some basic pattern matching for an expected format).

There's nothing stopping them entering 000-0000, but once only a disruptive idiot is going to make up a number when they've a perfectly acceptable number there.

I did this after spending days trying to find which builds a set of user stories went into. Yes it was to deal with a process failure else where, but it's still incredibly valuable information to track.

Answer 7

Good commit comments are like any good documentation, a cache for your slow and defunct brain or a cache of the result of any lengthy debugging/problem analysis/investigation.

E.g. whenever you spend time figuring something out, like debugging, analyzing logs or whatever, your findings and results are precious. Of course most tasks can be repeated, but it may take time. So you should always document your results.

Still, documentation takes time and sometimes it is felt as not necessary, like "we only had to do this once, so why write it down". That's ok, but as soon as you do the same thing a second time because you didn't document the results the first time, then it is of course clever to document the results.

So if your colleagues feel it is too much work to add commit comments, e.g at least point to the Jira case/Ticket that they were solving, well, then they might be motivated by the pressure of constantly responding to questions regarding the reason for each changeset.

In my opinion, documentation should be produced as a function of information being requested. For example, mail correspondence is a pretty good documentation system. Questions receive answers that can be later retrieved, that's how mailing lists and forums work in practice as knowledge bases.

Unfortunately, where I work, mail is being automatically deleted after 3 months, so it doesn't always work in practice.

Answer 8

Seek forgiveness, not permission.

While harsh, I did just this. I had a 50/50 split between people supporting and people opposing, most of who were the same level as me in the group. The arguments were "I can't be bothered" and "What is the point?". (Both indicating apathy and laziness, not genuine concerns).

I added pre-commit hook that simply measured the length of the string and gave a slightly humorous message before rejecting it. I put my name in the message so responsibility for "this outrage" was clear. Of course, "the opposition" could easily remove it, but digging into the scripts would take more effort than adding one more comment!

For a week I got messages added like ** (expletive deleted) or kjhfkwhkfjhw. After that, basic messages started appearing.

A year on and the sceptics use meanful comments and actually admit how short-sighted they were. I could never have got consensus, but I certainly got forgivenes and perhaps credibility. It works, people use it.

If you wanted to be more congenial (or feel that you would get in trouble), ask for permission to add a commit hook for a trial period. Say that if people don't like it in 2 weeks or 4 weeks, you will take it out. Chances are, they will lose interest...or grow to like it.

Answer 9

I usually convince people through:

• dialectic with good supporting reasons
• leading by example
• attrition

If I wanted our team to do something bad enough I would keep pestering until I get my way. I try to pester during those times where I can point out that we could have saved time/money had we already been doing X.

Additional good reasons for commit comments:

• Generating ChangeLog automatically from the comments.
• Audit trail for bug fixes, feature additions. This is useful both in and outside the team.
• Make commit mail more useful.
• Stop me from asking developer what commit X does (after almost every commit).

Answer 10

• Check you SVN logs for something obscure made 6 month ago.
• Ask some questions about this thing without telling when it's been done
• ???
• Profit

Answer 11

How do you make them want to add good comments?

From a experience with a colleague I just had. At the end of a project we had to write a summary document of all the changes made throughout the project. Not having made good commit notes my colleague found this task rather time consuming, and has now switched to making quite lengthy comments with each commit.

So - the takeaway - one solution could be to have developers write summary documents at the end of the project that detail what changes were made to what files, what files were added/removed and why.

Answer 12

Propose this to management behind closed doors:

The worst case scenario happens: All the senior level developers walk out the door.

As the company scrambles to fill empty developer seats, the management team is tasked with communicating the system's state to the client.

Ask them what they think would make their job easier in reconstructing the history of the app:

Reading plain English commits that clearly describe the changing state of the system?

Or would they prefer to look at code differences and figure it out themselves?

Answer 13

I guess one way to convince them would be to actually experience the pain that you are feeling.

For instance, let's say they are working on the following problem: They have a bug that, somehow appeared when another bug fix for the same code (oh the irony) was implemented. To be able to look this up from just searching through the commit messages would be great (and thus find out who wrote it).

Another way would be to explain to them that the commit message could be useful to give a hint as to why something was implemented in a certain way. Even if the commit message just says "feature X", you still can get a clue who implemented it, so you know who to talk to.

Answer 14

However, this doesn't seem to be enough to combat the two responses I always get:

1. It takes too long and I just want to get my changes into the repo.
2. It's easy enough to just look at the diffs.

Have you tried throwing down a challenge to your fellow developers so that they get some other benefit from putting in comments? One could look at this from either of a couple different angles:

1. Upping their game - This can be the trickier perspective to take but the idea here would be that they do this for some period of time and get used to the idea so that the habit is it would take longer to go the other way. Another point here is how much scrutiny would the comments get? If you are wanting a short story in the comment I could understand their point.
2. Subsidizing a change - This is where you'd have some kind of contest as a way to have the initial buy-in to try this out or offer some other kind of incentive to have the change be done for a while.

Something else to consider is how well do you know what your fellow developers are managing where you work? If they are trying to get 10 things done yesterday then I could understand that they may not want to change what they see as something that already works. Are you trying to tell them, "No, this doesn't work?" If so, then I can see how they may be a bit defensive or combative on this. If you are trying to tell them, "While this may work, there is an alternative that may be better..." then you may have a chance. Having a "Holier than thou" attitude here isn't going to help you, IMO.

Answer 15

Another way of looking at this is as a way for the developer(s) involved to grow their careers - they should own the documentation of their work.

In addition to other points raised in the above-referenced article, there is the ability to be able to review the code changes to find out where/when/why a change was done. That could be vital when tracking-down an elusive bug.

Answer 16

After you have convinced them that it is important to comment your commits, you can create a script that forces comments on commits, otherwise it will fail. You can even specify a minimum of characters to ensure its a meaningful comment. This will help them "remember".

However, it is important they understand the Why as @Kevin said, or else they'll just add anyt random comment.

Answer 17

Do you have code reviews? One thing that may help is to institute a rule that any commit or merge must be looked at and approved by another developer. Then if you are the reviewer, you would have to ask the developer making the commit to explain to you what he did. Once he does, you should ask him to type into the comment what he had just told you. Often when one cannot coherently explain the changes one made, it means that those changes should not have been made in the first place.

I have to say though, how can people object to something as obviously useful as commit comments? It does not take long at all, and it is a time well spent. Writing a comment forces you to think about what it is you have just done. It may even cause you to look at the diffs to make sure you indeed have done what you think you have done, and that you have not done anything stupid.

When you do not write the comments, you are being sloppy and undisciplined. And if you insist that you should not be required to write the comments, then you are being willfully negligent.

Answer 18

Tell them its the only way to have a chance at maintaining your procedural mess of 50,000 line methods, then consider writing better, more explicit code in the future so you don't have to deal with a bunch of pointless comments bloating your code base.

Answer 19

This is a process change item: Have a manager assign code developed by "x" to "Y" for quality assurance checks on the code alone, including QA of comments.

In my own organization developers are not allowed to perform final QA of their own code and check it in, this has to be done by another developer. Part of the QA Check is comments, so no comments, no check in. We do a lot of contract work where our "art" is actually someone else' contractual intellectual property, so others need to be able to understand and leverage our code. Also, there are times when projects come back to us after a long hiatus and we need to be able to pick up code 18-24 months later and understand the why, where and how we arrived at the code artifact in front of us. This provides a self-serving motivation to write commit comments.

Answer 20

Ask and get your fellow developers to do some merges and to look up history and compare a few files from the history.

Chances are that they will ask you to put comments the next day onwards.

Answer 21

Here's some advice:

1. Don't try to change the world. You will fail.
2. Instead you should regognize that everyone does work slightly different way. No one size fits everyone.
3. requiring some specific steps to people's work processes is very evil. Changing these processes takes 10 years. You're asking them to do this before next deadline.
4. Even simple process changes can take long time.
5. Some small comment on commits is way too insignificant to change these processes.
6. You can assume they do quality work, but should give enough freedom to choose the steps themselves. Some burdensome steps might not be needed for experienced developers.
7. If you're babysitting newbies, then stronger processes might be necessary, but experienced developers shouldn't deal with bullshit.
8. Imposing draconian restrictions on how work must be done is never ever going to work, it can only slow people down(might be good if they're too fast)
9. There are lots of people who think their way is the only right way to do things. Hope you're not one of them.

Answer 22

If your source control provdies it, turn on mandatory comments to prevent any un-commented commmits. Simple enough and everyone will soon realize that 5 seconds of typing a comment is painless.

But un-commented commits is one of the smallest negatives there is. I've been a part of many successful projects where not a single commit was commented. Don't get your panties in a bunch over it.