Source Control Checkin Comments at Top Of Source Files

Question

I've noticed a discrepancy with some source files in our system whereby some contain source-control checkin comments, and some do not. These comments are added automatically to the top of the file when it is checked in:

    * $Log:   //vm1/Projects/Morpheus/Sleep.bdy-arc  $
--
--   Rev 1.14   Apr 14 2009 15:32:52   John Smith
--Fixed bugs 2292 and 2230.

This seems to have been quite prevelant in all the compainies with which I have worked, but I must confess that I struggle to see the point. Generally the comments aren't that good, are ofen left by people who have long since departed, and even when they are of a high standard it is difficult to tie them to physical code changes.

It also strikes me, that you are physically changing the file that you are checking in. Now, this may not be such a problem with files that will be compiled, but could be a disaster with others, e.g. JavaScript files.

So really, my query is what was the motivation in concept behind providing this functionality in the first instance? Does anyone actually find these comments useful?

Also, I would be curious to know if this was feature that is commonly supported within Source Control systems. I am aware of it with PVCS, VSS and Subversion (Subversion Keyword Substitution), however I wonder if it is also available in some of the more popular DVCSs.

Your help, as always is much appreciated.

Answer 1

So really, my query is what was the motivation in concept behind providing this functionality in the first instance? Does anyone actually find these comments useful?

When the sources are mirrored to an external location (source packages, source code index etc) then the version control information might not be available. For such cases this information might be useful.

Answer 2

So really, my query is what was the motivation in concept behind providing this functionality in the first instance? Does anyone actually find these comments useful?

In some companies, audit controls are a big concern. Auditors want to be able to trace from the incident system to the actual code changes. Fixed bugs 2292 and 2230. provides a trace back from the code to the incident system.

Some companies require the incident number as a part of the source control change log comments for the same reason.

Answer 3

You are right - this is, on balance, not a very useful feature of revision control systems! Yes, companies like an audit trail, but this is provided by the revision control system's log command; yes, it means that the log is available if the revision control system is not - but in that case, Fixed bug 1234 probably isn't very meaningful :-) And, as you allude to, in order to tie the changes down to specific lines, you still need the help of the revision control system.

You are also correct that changing the file as it is being committed can give rise to issues - I once saw an issue where a colleague carefully ensured that his code compiled, then committed it, only to be flamed because the files he'd committed didn't compile. It turned out that the comment was something like Clean up /tmp/*.txt, and the C compiler was treating the /* as a comment-start character (and complaining because it was already inside a comment).

Another issue with logs in files is that they only make sense for linear working - once you're developing with multiple branches (in the way that distributed source tools like git/mercurial/bazaar encourage) having the log in the source file itself only serves to create merge conflicts almost all of the time.

For this reason, modern tools tend not to implement this functionality. Indeed subversion doesn't - its keyword substitution deliberately doesn't allow inclusion of log history.