I brought up in a meeting an annoyance that code changes were not commented within the code itself. We use SVN (Subversion) for source control, and it was relayed to me that you can just go into SVN and check the history and see the changes.

My question is is this a best practices? It seems easier to me to place the comment in the code itself with the defect/user story reference (we use Rally/Agile) AND in the svn header when you check in the changes. My bosses seem to think putting it the code is unecessary, and I told them I completely disagreed with that practice. I've always been taught that comments in the code are never bad. This is not my first gig.

I was even more floored when he told me his boss has been known to rip out comments in some code. After I stopped having the shakes, I wanted to... vomit.

What do you think about comments in code vs/with comments in source control and what do you do as a best practice?


2 Answers 2


Absolutely! They serve two completely different purposes.

  • Your commit messages are only describing why you're committing that particular changeset - customer request, fixing a particular bugs, etc. These would be where you log your user story references or bug references:

Revised method XYZ to cover additional use case highlighted by user story ABC.

Fixing bug 1234 which was caused by an off-by-one error in main loop

  • Comments in your code should describe why your code is written the way it is, or descriptive comments about the methods & variables (like headers to be processed by JavaDoc). See the example given at the end of the earlier answer.

The two concepts are independent. If you lose your source control, or migrate the code to a new VCS without retaining history, you've now lost all your documentation if you follow what your bosses suggest. And if you're trying to debug a system in production with no comments in the code, you're constantly flipping between reading hundreds of commits worth of SVN logs while trying to interpret the code & figure out what goes where.

The prospect of cramming the comments of hundreds of lines of code (which should be inlined with the code) into a single commit message is frightening.

  • I agree with you. About: "If you lose your source control" <--- this is part of the project and shouldn't be lost.
    – Alex Jurado - Bitendian
    Feb 4, 2014 at 14:59
  • 1
    Sure, your source control shouldn't be lost, but stuff happens.
    – alroc
    Feb 4, 2014 at 15:00
  • I completely agree with this answer, and is exactly what I described to my bosses.
    – Mark Goodwin
    Feb 4, 2014 at 15:24
  • Also, we went for SourceSafe to SVN a couple years ago and DID NOT bring over the history, so that can happen. All you are left with is the last SourceSafe state to start your SVN revision history from. Luckily I am concious of commenting code, so all my previous changes are at least in the codebase.
    – Mark Goodwin
    Feb 4, 2014 at 15:39
  • @MarkGoodwin - Aside from the problem of starting with SourceSafe, your real problem is that your working environment doesn't place value on history. SourceSafe can be migrated to Subversion with no loss of history, you needn't have lost anything. Feb 7, 2014 at 13:10

I think there is not a general answer. It depends. Extra-commenting the code may bring noise and make it less readable.

Comments in the code like these:

// 2014/01/17 [email protected] changed this path:

Shouldn't be there. They should be in the version control comment, along with other changes. Also, you should have a ticketing system in which this change is reported. Say you have an issue in your ticketing system numbered 12345. Then, whenever you want to see what was done and why, and who asked for changing this url, etc. you would go to your ticketing system and look for it. Then you would find related issue numbered 12345. Then you should grep subversion history for issue 12345 (good practice to add related issue number in your commit comment), etc.

But, comments like these:

// path must be retrieved from file_helper broker, as it crashes otherwise because...

Are very useful and they are worth to be there forever.

  • Agreed. Extra commenting is noise, but functonal commenting is very useful, and I think that is the distinction you are making here.
    – Mark Goodwin
    Feb 4, 2014 at 15:34
  • Also, we (or, I, i should say), always use the DEFECT or USER STORY number in my comments so a quick search tells me where all the changes took place in my codebase. My bosses think this is wasted effort. I guess that is why they are managers now.
    – Mark Goodwin
    Feb 4, 2014 at 15:36
  • @MarkGoodwin - Yeah, that's wasted effort. If I want to know the history of the code, svn log and svn blame will tell me that much better than the most recent collection of "I changed this" comments. Alex is right - comments should focus on why things are done a particular way, especially when it seems unusual. Feb 7, 2014 at 13:02