Coding Standards – Are ‘Edited By’ Inline Comments Norm in Revision Control?

coding-standardscomments

The senior dev in our shop insists that whenever code is modified, the programmer responsible should add an inline comment stating what he did. These comments usually look like // YYYY-MM-DD <User ID> Added this IF block per bug 1234.

We use TFS for revision control, and it seems to me that comments of this sort are much more appropriate as check-in notes rather than inline noise. TFS even allows you to associate a check-in with one or more bugs. Some of our older, often-modified class files look like they have a comment-to-LOC ratio approaching 1:1. To my eyes, these comments make the code harder to read and add zero value.

Is this a standard (or at least common) practice in other shops?

Best Answer

I usually consider such comments a bad practice and I think this kind of information belongs to the SCM commit logs. It just makes the code harder to read in most cases.

However, I still often do something like this for specific types of edits.

Case 1 - Tasks

If you use an IDE like Eclipse, Netbeans, Visual Studio (or have some way of doing text searches on your codebase with anything else), maybe your team uses some specific "comment tags" or "task tags". In which case this can be useful.

I would from time to time, when reviewing code, add something like the following:

// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla

or:

// FIXME: [2010-12-09 haylem] marking this for review because blablabla

I use different custom task tags that I can see in Eclipse in the task view for this, because having something in the commit logs is a good thing but not enough when you have an executive asking you in a review meeting why bugfix XY was completely forgotten and slipped through. So on urgent matters or really questionable pieces of code, this serves as an additional reminder (but usually I'll keep the comment short and check the commit logs because THAT's what the reminder is here for, so I don't clutter the code too much).

Case 2 - 3rd-Party Libs' Patches

If my product needs to package a 3rd party piece of code as source (or library, but re-built from source) because it needed to be patched for some reason, we document the patch in a separate document where we list those "caveats" for future reference, and the source code will usually contain a comment similar to:

// [PATCH_START:product_name]
//  ... real code here ...
// [PATCH_END:product_name]

Case 3 - Non-Obvious Fixes

This one is a bit more controversial and closer to what your senior dev is asking for.

In the product I work on at the moment, we sometimes (definitely not a common thing) have a comment like:

// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ

We only do this if the bugfix is non-obvious and the code reads abnormally. This can be the case for browser quirks for instance, or obscure CSS fixes that you need to implement only because there's a document bug in a product. So in general we'd link it to our internal issue repository, which will then contain the detailed reasoning behind the bugfix and pointers to the documentation of the external product's bug (say, a security advisory for a well known Internet Explorer 6 defect, or something like that).

But as mentioned, it's quite rare. And thanks to the task tags, we can regularly run through these and check if these weird fixes still make sense or can be phased out (for instance, if we dropped support for the buggy product causing the bug in the first place).


This just in: A real life example

In some cases, it's better than nothing :)

I just came across a huge statistical computation class in my codebase, where the header comment was in the form of a changelog with the usual yadda yadda: reviewer, date, bug ID.

At first I thought of scrapping but I noticed the bug IDs did not only not match the convention of our current issue tracker but neither did they match the one of the tracker used before I joined the company. So I tried to read through the code and get an understanding of what the class was doing (not being a statistician) and also tried to dig up these defect reports. As it happens they were fairly important and would have maed the life of the next guy to edit the file without knowing about them quite horrible, as it dealt with minor precision issues and special cases based on very specific requirements emitted by the originating customer back then. Bottom line, if these had not been in there, I wouldn't have known. If they hadn't been in there AND I had had a better understanding of the class, I would have noticed that some computations were off and broken them by "fixing" them.

Sometimes it's hard to keep track of very old requirements like these. In the end what I did was still remove the header, but after sneaking in a block comment before each incriminating function describing why these "weird" computations as they are specific requests.

So in that case I still considered these a bad practice, but boy was I happy the original dev did at least put them in! Would have been better to comment the code clearly instead, but I guess that was better than nothing.

Related Topic