10

In fact, I always have something to put in when I perform a check-in of my code. However, the question I have is - Is it really so necessary? Does it help so much? How?

From one point of view, comments can help you to keep track of changes performed with every check-in. Thus, I will be able to analyze the changes and identify a hypothetic problem a little bit quicker.

On the other hand, it takes some time to write useful information into check-in.

Is it worth it? What are the pros and cons of writing comments to every check-in? Is there any way to write "efficient" check-in comments?

20 accepted

Comments for check in are very useful, if not downright essential.

But they need to contain correct info to be useful.

  1. Like with code comments, don't write a detailed "what". A high level description of the change will suffice. Instead, write WHY you made the change

  2. Include meta data. Bug fixed #/Request Ticket # addressed. How you tested this particular change (good idea is to map checkins to new test cases for them, e.g. Testopia or whatever way you track your test cases)

As for why the comments are useful:

  • Code maintainer (you or likely someone else) will understand how code morphed qualitatively by perusing a single log

  • You can quickly figure out why a particular line of code changed by seeing which version had the change and looking in checkin comments for that version

  • If you work for any large size organization, auditing, auditing, auditing

  • By compiling good checkin notes for all checkins that go into a release, you will have a VERY good first draft of release notes.

2

It sure is worth it!

  • We have made the experience that even putting a single word can help you get into the project when you're new to it.

In our company we have lots of projects that don't get updated very frequently.

  • Not having a comment because of laziness doubles the time to get what actually has changed in the code and to even get an idea of what you were trying to do.

  • Recently we had this issue when we were tracking a bug and lost a lot of time just understand the coding of the feature that was implemented in those comment-less check-ins. (2k+ LOC).

So always remember to write a little, precise phrase, it's definitely worth the seconds rather than the hours later on!

And the history looks darn attractive when there is no white space ;-)

2

One important pro-point is that you can instantly see what type of work another committer has done. Another one would be that you can take a look at it after some time and still know what it means. Therefore you don't have to check the code to see things that have changed.

You can automatically generate a changelog you might display in the release notes of your application. For sure this only works if everyone clearly describes the changes.

And there are changes that cannot be reflected in source code. Sometimes you need to upload binary files or create some specific directory structure. To explain the reasons for this type, you would need to create some file and add that one to the repository which isn't really a version control of the changes...

The reasons are a bit the same like for commenting source code.

Contra: It takes everyone some time away to spend with typing in a comment.

regards

1

If you don't write a comment how are you going to remember why you made the edit 6, 12 or 18 months from now? More importantly, how is the next person who has to modify your code going to know?

After all the next person to edit your code might be an axe wielding psychopath

1

I typically use the email thread from the Code Review as the check in comment in source code control. There is so much valuable feedback that occurs during the code review process including

  • Debate over alternative solutions
  • Justification to real people as to why the change is necessary
  • Mistakes made in earlier revisions
  • Issues that were raised and handled or discarded

Comments and / or beautiful code simply can't capture these dynamics and they clearly add value to the process. Years later other developers can get a crystal clear picture of the general scenario around a particular fix with this type of model.

1

It may seem trivial to say it, but checkin comments are to changes what code comments are to code. The change you are committing is the what, but you need to add a checkin comment to give the why. The person person who maintains the code after you should not have to do an analysis of diffs to work out what the intent of the change was.

If writing a checkin comment takes you more than a few moments, perhaps you should look at how you structure your checkins. Like a good method, a change should do a single conceptual thing. If you are making several overlapping changes at once it could explain why you find writing checkin comments a pain.

1
  • Putting a bug id/task id in the comment to identify which changes affected which bugs/tasks, who wrote the fix/fucntionality and what files were affected by the fix/functionality
  • Using the comments to identify a previous version to rollback to during active development, e.g. I code for 2 hours with 3 checkin's during that period and then decide that I don't like what I've done, I can find my previous comment and rollback to it (tho rolling back to more that the last checkin hardly ever happens)
  • Identify why the code was changed - pretty important when justifying the time spent on a task/fix too your boss
1

It is important because it makes it easier to identify changes. Some reasons why this need arises are: (1) You boss ask you what you did and now you have something that is a quick reference (2) There is a bug and you need to narrow down what change caused it (3) Someone made a major mistakes and you want to find the update prior to the mistake (4) You want to appear prudent- helps when it time for $$$-raise

Everyone else gave good reasons too. However, it is okay if you feel like you do not need to. It makes sense too. Just remember though that having to actual read code comments to remember changes or read code because some Software Engineer never comment their code- and do it very quicky because of the reasons I gave; is not fun.

0

Of course it's worth it - there's no reason for someone to have to examine the diffs to figure out what you did. The comments give a brief explanation of changes made.

Efficient comments should address:

  • What change was made.
  • Any bugs that were fixed by the checkin.
0

So that other users of your code know what you have changed (if anything). This is vital in accountability and auding the work of developers in a team.

-1

They are very useful. When using with a bugtracker system they may be invaluable.

They are also useful, to say you've fixed a webcomic:

http://imgur.com/73EAu.png

- Add dri2-page-flip.patch to enable full screen pageflipping. Fixes XKCD #619.