Modifying existing code, what's your commenting style?

Question

When you modify existing code, how do you comment the code?

i.e.

// changed code to ...
// by: blankman
// modified: 20081204

Looking for a nice format ...

Answer 1

Do you not use source control? A simple diff lets anyone interested see exactly what you changed. A note in the source control system citing what change request the change was made for lets anyone interested go look at the requirements to see the why.

Why would you cruft up your code with excessive and needless comments?

Answer 2

I recommend using a version control system for such documentation, such as Subversion or CVS

Answer 3

If at all possible, this is the type of meta-information that works best as a comment in the revision control system, not cluttering the code itself.

Answer 4

Do you have version control - something like subversion will keep great change history if you set it up right and it keeps the code nice and readable!

Answer 5

Source control (such as SVN blame) can keep track of that.

I don't like to clutter the comments with modified timestamps if the file is under source control.

As other posters have noted, it's reasonable to add such "metadata" on occasion, but I haven't adopted a set convention for the formatting since I avoid the practice in general.

Answer 6

I avoid putting information about when/why code was modified in the source code. Instead I use a source code repository and include descriptive comments when I check code in. Your source files will get cluttered if you embed a change log.

Answer 7

I usually go with :

// changed code because...
// 4-Dec-2008/JMC

Answer 8

I agree with the source control suggestions, however I do like to add a comment in the case where I'm fixing a bug and the change may not be entirely obvious. In this case, I'll reference the bug number (i.e. JIRA number) and a short description of what the bug is (so that people editing the code later will not re-introduce the bug).

For example:

// Fixing CLIENT-3847: if we don't set the foo attribute on the bar here, the baz will crash

If they want to see who made the change, they can look at the source control revisions.

Answer 9

I think there is a middle ground between the people who describe the whole thing in the file and the people who rely on version control. I use version control comments, but if you end up doing something that a later maintainer might think is redundant and remove it, you need a comment to explain why. Or if it's something that has ping-ponged between two alternate ways of doing something, explain why it's the current way. I hate to say it, but there is a section of my program that looks like:

  // PCR:1245 Changed to be depth-first per new business requirements
  // PCR:1248 Changed back to be width-first per new business requirements
  // PCR:2222 Changed back to be depth-first per new business requirements

Answer 10

Use version control to control the documentation of what has changed. You don't need a change log in your source code, that's what SVN, etc, does for you. Not that many people use this properly.

Use comments to describe why the code is now how it is, with no reference to the old implementation. Hopefully by coding to an interface, or at least methods that do a task, the comments won't have to change, and the implementation can change happily with only necessary inline comments.

In addition sometimes code can be non-obvious in implementation because of a bug, etc. In that case, document the bug there and then so someone doesn't clean up the code and re-introduce it.

I'm not in favour of linking to external documentation when it comes to specific functionality (rather than the wider scheme of things), as it creates a disjoint between the code and the specification. If there's a business requirement like "we need a count of the customer's credit records where they have gone into arrears", then comment it there and then before the code that does it. Don't say "// implements Spec_1004" because I will personally come and kill you when I see that code.

Answer 11

Many version control software can expand embedded tags such as $Id$ during check-in embedding the filename, version number, time-date stamp, username, branch, etc. Each time the file is checked in the expansion will be updated

I use this as the header (1st) line of source code that I write: // $Id$

This one doesn't replace expansions, but keeps appending for each check-in (can be good in key files touched by many developers): // $Log$

See CVS keyword expansion

Answer 12

'ALS MM/DD/YYYY

Makes it easy to find all of the changes relating to a specific fix. Especially when you are working with a larger project (> 50 classes) have not yet checked in any source code.

Answer 13

I normally leave a comment as follows:

// Updated by Bug: 12345 (Bugzilla)

Or

// Bug 12345

That way, anyone who cares can simply go to the Bug tracker to find out why it is the way it is, and it leaves me a sort of breadcrumb trail in case I need to research a related issue.

It's important to note that I keep a Composition book/Journal that I list Bug numbers in followed by the action I took and what I found out while researching that bug.. The reason is 1) We don't have a wiki yet (but will), and 2) it forces me to write my thoughts down coherently, instead of the stream of conciousness writing that comes if it's easier for me to put away.

Answer 14

There is one case where I'd argue using such a commenting style is the right thing to do: when you are doing maintenance on some script whose ownership crosses all sorts of organizational boundaries. You may be the person making a tweak to the code now, but six months from now it may very well be some previous author (one of many) wondering what the heck has been done to the code and who has no way of getting in contact with you. I'm talking about the kind of situation where you have no leverage whatsoever to get other people to use your source control, bug tracker, or what have you.

Otherwise, I agree with the consensus here that such commenting is superfluous.