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:

It takes too long and I just want to get my changes into the repo.
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?

Do you need to meet any particular standards, for example ISO or CMMI certification? If you do, convincing management becomes significantly easier. Aside from that...good luck. If you can't convince other developers even after showing them the benefits, I'm not sure how you can convince management. — Thomas Owens, Sep 20 '11 at 13:41
Well there goes that idea, since you can tie commit log messages into a meeting the goals of a few KPAs from CMMI (and I'm assuming various ISO standards as well, although I'm not as familiar with those as I am with CMMI), it would be easy to convince management that they will serve a goal with auditing and force developers to follow them. But without that, it's tough to implement process improvement without support from the developers and other hands-on people. — Thomas Owens, Sep 20 '11 at 13:46
@ChrisSimmons: To make them want to want to comment... have you tried hypnotism? Seriously, I don't think they will want to do it unless they either: 1) experience some sort of problem stemming from a lack of comments 2) are able to gain some immediate benefit. — FrustratedWithFormsDesigner, Sep 20 '11 at 13:49
@FrustratedWithFormsDesigner: Heh, I left my pocketwatch at home. I agree they need "pain" (in the right direction) or reward. Right now, they feel pain when imposed upon to summon up a quick thought as to why they are making the change they are making ... wrong direction :( — Chris Simmons, Sep 20 '11 at 13:52
@ChrisSimmons: Maybe if you made a report that automatically extracted the comments from the commits to make meetings go faster since the comments are already there... but that only works if you have defect meetings where those types of reports are useful. — FrustratedWithFormsDesigner, Sep 20 '11 at 13:56
Actually, @FrustratedWithFormsDesigner, that would work for any status meetings. I should start doing that for my weekly status reports/meetings. Although more recently, I've been working on non-code tasks, where the documents are in SharePoint instead of version control, and I'm not sure how to do that for SharePoint. — Thomas Owens, Sep 20 '11 at 14:11
"Takes too long"? I never remember spending more than a minute on any comment to source control. More like 10 seconds. — jsternberg, Sep 20 '11 at 14:24
On the "cause them pain" angle, the best way to do this is to hit them with "I can't find your commit that fixed issue X" a few times. (Though even the best way to cause pain won't work as well as a positive incentive.) — David Schwartz, Sep 20 '11 at 22:50
@DavidSchwartz many people would take that as being very confrontational... "WHY do need to see my commit? What are you accusing me of?" etc... — nickf, Sep 21 '11 at 00:53
@nick: That's possible, you have to be able to defuse such confrontations with an innocent explanation, ideally a plausible one. (I'm facing a similar issue, for example.) — David Schwartz, Sep 21 '11 at 01:00
if you use bug tracking software for issues, adding a comment to a commit can be as simple as #10291. The reference will be immediately apparent, and all the relevant details should already be in the bug tracking system. — zzzzBov, Sep 21 '11 at 04:07
@zzzBov He's tried that: "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." — Hugo, Sep 21 '11 at 05:55
using SVN we force a comment to be entered or else you cant commit the code. its simple and works. — Mauro, Sep 21 '11 at 08:06
@jsternberg: My experience is much the same, but that depends a lot on the granularity of the commits. These days, my commit comments are rarely even a single complete sentence because I'm using git and committing every time I complete a minor sub-task, but they used to be a lot longer back when I was using CVS and only committing once a day. Perhaps OP's team is more on the "once a day" end of the spectrum? (In which case the better question might be how to get them committing more frequently...) — Dave Sherohman, Sep 21 '11 at 10:44
Enforcing a comment on a commit is all very well but unfortunately it's all too easy to type -m" "... — Ben, Sep 24 '11 at 10:30
see also "How do you encourage project members to document their work for end-of-project handover?" — warren, Sep 26 '11 at 17:43

score 78 · Accepted Answer · answered Sep 20 '11 at 13:30

78

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.

answered Sep 20 '11 at 13:30

Kevin D

3,426

It is likely not about the "why." There are people who get into a rut and refuse to learn. They need motivation, not an ever increasing barrage of explanations. – riwalk Sep 20 '11 at 14:27
1

In this case, I think answering the why of a check-in is precisely what you're after: giving the developers a good reason (A.K.A. motivation) why they should use (meaningful) check-in comments. – user Sep 20 '11 at 14:39
5

It's a matter of convincing the person who can make the call. The appropriate response is: "There were seventeen commits yesterday for no apparent reason. Seeing as they do not contribute to any outstanding bugs or issues, they've been rolled back." – Chris Cudmore Sep 20 '11 at 17:26
2

You need to use a friendly persuader. – SoylentGray Sep 20 '11 at 17:38
1

There's the old close code "WAD" - Working As Designed. There's also the joke close code "WAC" - Working As Coded. It's nice to be able to tell the difference. – Wudang Sep 20 '11 at 21:12

score 33 · Answer 2 · edited Sep 20 '11 at 22:08

33

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.

edited Sep 20 '11 at 22:08

Austyn Mahoney

155
1
1
9

answered Sep 20 '11 at 13:33

Bill Leeper

4,125
16
20

4

I like the idea of the status report angle. The "person who can make the call" I mentioned would like that for their own status reports so may be a selling point at that level. – Chris Simmons Sep 20 '11 at 13:41
14

+392,481 for the "good commits will work in lieu of a weekly status report." It is obvious that showing them "why" has not helped and will not help. Creative solutions like that will help them develop good commit messages. – riwalk Sep 20 '11 at 14:26
Me too. Back when I had to complete a lot of fine-grained time-sheets I would use the commit time stamps to estimate how much time I spent on each task. – mikerobi Sep 20 '11 at 20:49
1

"Make them...deal with support." is the winner for me. After having supported a legacy product for a few years, I cannot bring myself to commit code without some kind of comment. – Malachi Sep 20 '11 at 22:34
I wonder if I could use this angle to convince my manager to cut back on status meetings (currently at 3 per week for a 5-man dev team). – greyfade Sep 20 '11 at 22:58
Sounds like they don't have a problem doing the merges by looking at diffs. – snakehiss Sep 21 '11 at 02:06

score 26 · Answer 3 · answered Sep 20 '11 at 13:50

26

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.

answered Sep 20 '11 at 13:50

P.Brian.Mackey

11,103

4
365,000 for this. I don't understand why writing a sentence is so "difficult and time consuming" when doing a diff takes LONGER.

Jennifer S

Sep 20 '11 at 15:35

2

I call it "giving a cr*p about your cohorts." You should almost never have to look at diffs, much less as a matter of course (and apparently-current policy). – Eric Sep 21 '11 at 03:52

score 22 · Answer 4 · answered Sep 20 '11 at 16:28

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.

score 12 · Answer 5 · answered Sep 20 '11 at 15:21

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.

"People spend hours or even days fixing something and an extra 2 seconds to type in a commit message is too long?!" Hey, I see people walk miles inside a store, but when back at their car, somehow it's too far to push their shopping cart fifty feet to the cart corral. Lazy people are too lazy to consider precisely how lazy they're being. — Kyralessa, Sep 24 '11 at 03:25
That's also why dead code (i.e. commented-out code) should be removed, not left commented out for a year. — cthulhu, Sep 24 '11 at 14:42

score 10 · Answer 6 · answered Sep 20 '11 at 15:56

10

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.

answered Sep 20 '11 at 15:56

Binary Worrier

3,112

1

-1 He said he can't turn it on. – snakehiss Sep 21 '11 at 02:05
@dietbuddha: But he has another argument for turning it on, and no one had mentioned a pre-commit hook before. – Binary Worrier Sep 21 '11 at 08:27

score 7 · Answer 7 · answered Sep 20 '11 at 14:04

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.

score 6 · Answer 8 · answered Sep 20 '11 at 20:41

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.

snakehiss · Answer 9 · 2011-09-24T00:33:01.337

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).

score 3 · Answer 10 · answered Sep 20 '11 at 16:18

3

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

answered Sep 20 '11 at 16:18

Arkh

591
3
8

score 2 · Answer 11 · answered Sep 20 '11 at 17:44

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.

score 2 · Answer 12 · answered Sep 20 '11 at 22:49

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?

score 1 · Answer 13 · answered Sep 20 '11 at 13:42

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.

score 1 · Answer 14 · answered Sep 20 '11 at 13:55

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

It takes too long and I just want to get my changes into the repo.

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:

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.
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.

score 1 · Answer 15 · answered Sep 26 '11 at 17:46

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.

score 0 · Answer 16 · answered Sep 20 '11 at 14:56

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.

score 0 · Answer 17 · answered Sep 20 '11 at 16:33

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.

score 0 · Answer 18 · edited Sep 21 '11 at 00:12

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.

score 0 · Answer 19 · answered Sep 20 '11 at 19:52

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.

score 0 · Answer 20 · answered Sep 21 '11 at 07:57

0

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.

answered Sep 21 '11 at 07:57

bhagyas

409
3
7

score 0 · Answer 21 · answered Sep 24 '11 at 01:12

Here's some advice:

Don't try to change the world. You will fail.
Instead you should regognize that everyone does work slightly different way. No one size fits everyone.
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.
Even simple process changes can take long time.
Some small comment on commits is way too insignificant to change these processes.
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.
If you're babysitting newbies, then stronger processes might be necessary, but experienced developers shouldn't deal with bullshit.
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)
There are lots of people who think their way is the only right way to do things. Hope you're not one of them.

score 0 · Answer 22 · answered Sep 24 '11 at 03:23

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.

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

22 Answers22