We use subversion - Should we place comments in my code anyways?

Question

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?

Answer 1

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 bob@mymail.com changed this path:
$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...
$path=file_helper::get_path(...)

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

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