Take the 2-minute tour ×

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


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

Looking for a nice format ...

share|improve this question
add comment

closed as off topic by Raghav Sood, WarrenFaith, Ahmad, Reno, brian d foy Jan 14 '13 at 17:00


14 Answers

up vote 37 down vote accepted

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?

share|improve this answer
Just wanted to elaborate a little bit... I've worked on a few years-old systems, with lots of old-school developers that had come before me that followed a commenting style of this type. After a while you end up with lines and lines of comments documenting changes. I delete them all. –  sliderhouserules Dec 4 '08 at 18:08
Comments are not compiled. Live and let live. –  StingyJack Dec 4 '08 at 18:23
When 90% of my work time is spent in uncompiled code I think it's pretty relevant what is and is not in there, no? –  sliderhouserules Dec 4 '08 at 18:33
I forget that I have the option of collapsing XmlComments (everything is kept in there) and that you may not have that option to remove clutter. –  StingyJack Dec 5 '08 at 13:56
add comment

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!

share|improve this answer
what do you have to do to set it up right? –  Blankman Dec 4 '08 at 17:25
add comment

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.

share|improve this answer
add comment

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

share|improve this answer
add comment

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.

share|improve this answer
I was about to write exactly the same points. In short: The code is about the present, the past is what version control is for. –  myplacedk Dec 4 '08 at 18:14
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

I usually go with :

// changed code because...
// 4-Dec-2008/JMC
share|improve this answer
That really clutters your code, you should really check out Subversion. –  Fernando Briano Dec 4 '08 at 17:28
I do use Subversion. Nevertheless, I like seeing, in my code, what my code is doing, without having to using an external app. –  James Curran Dec 4 '08 at 17:30
But you aren't really adding anything to tell you what the code is doing with those 2 lines. You are adding something to say why you made a change. –  EBGreen Dec 4 '08 at 17:40
@EB, Isn't that the same thing??? "Changed code because...". Its easier to look at the comments than getting VSS to diff and look at the changes, and try to decipher what those changes do now as opposed to before. –  StingyJack Dec 4 '08 at 18:21
I might buy that the explanation has value, but I certainly don't see the value of the date. –  EBGreen Dec 4 '08 at 18:23
show 2 more comments

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.

share|improve this answer
Unit tests obviate the need for this. –  sliderhouserules Dec 4 '08 at 18:03
Not all problems can be encapsulated in a unit test. Suppose the baz is in a different module, and the relationship is complicated. Suppose the next developer wants to have some inkling he might break something before testing. Comments that explain why code is the way it is can be very valuable. –  David Thornley Dec 4 '08 at 18:41
Seems like such information should be added to the method documentation section (javadoc, etcetera). –  PEZ Dec 21 '08 at 22:02
add comment

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
share|improve this answer
Unit tests cover this ground quite well. Comments like this are almost never needed. –  sliderhouserules Dec 4 '08 at 18:04
The latest comment is possibly worthwhile (although "depth-first per new business requirements" is a really lousy comment, since I have never seen a business requirement for a particular search method). The previous ones should be removed, as they mean nothing for the current code. –  David Thornley Dec 4 '08 at 18:38
@David - what makes you think this has anything to do with search methods? In this case, "depth first" and "width first" are the different ways of applying some user specified rules. –  Paul Tomblin Dec 4 '08 at 21:27
Still, unit tests will inform people much better. –  PEZ Dec 21 '08 at 22:04
add comment

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

share|improve this answer
add comment

I normally leave a comment as follows:

// Updated by Bug: 12345 (Bugzilla)


// 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.

share|improve this answer
add comment


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.

share|improve this answer
add comment

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.

share|improve this answer
add comment
