Why are check-in/commit comments a required field in some source control systems?

tags:

version-control

views:

243

answers:

+4 Q:

Why are check-in/commit comments a required field in some source control systems?

In Perforce (atleast the GUI) a check-in/commit comment is required. (I don't believe they are required in Git or Subversion.) Most developers that work with me just fill it in with latest/updated/etc. I used to write meaningful descriptions, but at about 20 comments a day with stuff like 'replace an image.' 'Changed spelling of 'franhcise' gets really annoying. Furthermore most changes can be quickly seen in a Diff.

At first I thought I was just being lazy, but I tend not to even look at them when reviewing other peoples code. I'd rather go right to the Diff. Am I alone? Are required comments a good idea?

+10 A:

You should always leave good comments. Not necessarily describing what you changed, unless it is a large changeset with too many distracting little details... but always, always, describe why you made the change (maybe link to a bug tracker item if there is one).

When i'm looking at your diff a year later, after realizing that it introduced a subtle bug, i need to know why the change was made - if i can't find a good reason, i'm just going to roll it back and curse your lazy ways... ;-)

Shog9 2009-01-13 19:22:25

Don't you see the point of the question? Significant changes do deserve a good description. But making comments for small changes can get too tedious too quickly. As the question stated, a diff can do a much better job. A diff is always more accurate.

Khnle 2009-01-13 19:31:53

But it is tedious in the long run to do a report and look at every diff... far easier to run a history of all changes with their comments. Ones with useless comments are suspect.

Tim 2009-01-13 19:34:18

More accuracy does not necessarily equate to more useful or better. If you're rushing to catch a train, ask me the time, and i delay you while contacting the Naval Observatory to give you millisecond accuracy... You will not be well served. Tim makes this point well in his answer...

Shog9 2009-01-13 19:36:57

But the point is: How are "latest"/"updated"/etc. more useful than an empty line? And if you are not going to leave *any* comment in the first place, will an obligation really make you write a *good* one?

Pukku 2009-01-13 19:39:37

...and even if you have the diff ready in hand, it won't tell you why the change was made. Are you fixing typos because of a company-wide project to improve spelling, or was it just bugging you that day?

Shog9 2009-01-13 19:39:43

"will an obligation really make you write a *good* one" - the obligation has to come from you. Just like writing good code. I'm shocked this is even a problem - if you have to stop and think about why you're checking in something, then maybe you should have put more thought into the change initially

Shog9 2009-01-13 19:41:48

Now we are talking. So if the obligation comes from me as it should, then why does the software have to enforce it? Ok, maybe just to remind me in case I'm accidentally going to make a premature hit on Enter...

Pukku 2009-01-13 19:43:36

"Are you fixing typos because of a company-wide project to improve spelling, or was it just bugging you that day?" -- maybe not the best example ... A year later, I most probably couldn't really care which reason you had to fix that typo.

Pukku 2009-01-13 19:49:06

Unless you screwed it up. Then, i'll care. Look, if we were perfect, then we wouldn't really need source control.

Shog9 2009-01-13 19:50:26

As for software enforcing it, i've never used any that would require anything more than a non-blank entry; if you really don't care, "sfakjs;d" is valid. But you should care. Deeply. Because it's your work.

Shog9 2009-01-13 19:51:37

I agree completely. But I also believe that from the point of view of someone reviewing a long list of revisions and their comments, an empty line is less clutter (and less annoying) than "sfakjs;d".

Pukku 2009-01-13 19:57:03

A lot of this has to do with your role in the company and the responsibilities you have. If your job is just to crank out code, then this may be a distraction from your work. If your job entails managing releases, improving process and tools, then this is another item that matters.

Tim 2009-01-13 19:57:29

Laziness in this area is like laziness sin all other areas of our work. Shortcuts now have costs later. Good practices and infromation while you have the context saves LOTS of time.

Tim 2009-01-13 19:59:21

@Tim: All this time I've been thinking of this from everyone's perspective. Moreover, I believe also programmers frequently need to (or have the luxury to) look at the revision history, so I'm not so sure of the role-based difference. Look, I never objected against good and useful comments, ok?

Pukku 2009-01-13 20:05:01

@Tim: well said.

Shog9 2009-01-13 20:05:56

My point is just that if you (or your devs) are determined not to write a useful comment, no enforcing on the tool level is going to help, just as Shog9 pointed out - so why do it? This was the question. But maybe it's just redundancy (in a good way): if you forget your obligation for a while...

Pukku 2009-01-13 20:08:39

Mostly because they are not meant to be used for making commits after changing a css attribute etc., but rather after making a more meaningful change/bugfix. But comments are very useful anyways.

Vasil 2009-01-13 19:24:23

+5 A:

Perhaps a bit of a different perspective:

If you want to review ALL the changes for a year or since the last release - do you want to look at all the diffs, or would you like to see a good commit comment and a link to a defect/issue item?

Tim 2009-01-13 19:27:09

Excellent point - even if the reason for the change is easy to see from the diff (as in the case of a typo fix), it still requires going the extra step to *get* the diff, when a two-word comment would have saved you the trouble.

Shog9 2009-01-13 19:33:28

exactly. A developer may not see this viewpoint, but more senior people or leads, or managers often do. Trying to make sense of a list of 200 commits is challenging - when there are useless comments it is a nightmare. Don't make me have to look at diffs for each one.

Tim 2009-01-13 19:37:17

+6 A:

Meaningful comments serve several purposes:

If you're looking for a particular change in a version history, they let you quickly scan through the file's history (eg: "Hey, I know we fixed a bug about the flicker of this widget sometime in March last year. Do you remember what was the fix for that?").
They encourage you to make atomized commits. If you end up making check-ins with generic comments, that probably means you're doing too many things at once.
As mentioned earlier, they let you know why things changes. Sure, a diff can tell you, for instance, how the tax computation changed for item such and such. But it won't tell you that it's because law XYZ for taxation changed.
They make it easier to write release notes, or equivalent documentation.

Kena 2009-01-13 19:27:46

Nice summary. ++

Shog9 2009-01-13 19:33:58

+2 A:

If you're making 20 check-ins per day, you're probably checking in too frequently. Group all the minor typo fixes into a single checkin with a comment of "fixed various typos".

C. Dragon 76 2009-01-13 19:30:06

if you knew how many different projects my boss makes me juggle... :D

Shawn Simon 2009-01-13 20:02:35

+2 A:

Writing a meaningful comment takes about 30 seconds, so just get over it and do it.

starblue 2009-01-13 20:01:11

Agreed. And to write "typo fixed" et al. takes maybe 5 seconds. You don't need to specify which typo you fixed, and in what way; the point is that your change is most probably something that a future reviewer of the revision history can skip, as he's probably looking for something ...

Pukku 2009-01-13 20:57:02

... completely different. But if you fail to type even that, then the reviewer *does* need to get a diff, because he wouldn't know whether or not your change might be relevant - and that *is* annoying when there's a lot of it.

Pukku 2009-01-13 20:57:35

+2 A:

As has been discussed in the comments to Shog9's answer, enforcing the comment on the tool level does not necessarily help keep the lazy people in line, because the requirement is too easy to circumvent (as was already mentioned in the question: just type "latest"/"updated"/etc, or even "sfakjs;d", which is probably more harmful than an empty line).

However, the fact that the tool requires it may serve as a reminder for a normally diligent developer who is accidentally going to commit without any explanation. If it does this even once, then we are on the plus side (i.e., the requirement is beneficial), because normally the functionality does not make any difference – the good guys write the comments anyway, whereas the bad gals can always get around the requirement, no matter what technical barriers you set up. (Whether you want to keep them employed is another question, of course.)

Pukku 2009-01-13 20:20:50

ansaurus

tags:

views:

answers:

Why are check-in/commit comments a required field in some source control systems?

related questions