Should you comment changes in code and in the changelog?

Question

I have notice a trend for developers to comment their changes less with the justification that the purpose/date/reason is in the changelog. They have some very justifiable claims that duplication of effort is occuring if we require both. I am spending some serious amount of time tracking down changes. No specific direction has been given and the lack of a consistant approach has me a little peeved. Typically are people doing both? Are there tools I might want to try out to reduce the hunt down time. Currenltly we have cvs, git, and svn implementations.

Hawkie

Answer 1

Comments in the code should describe the what the code currently does. These comments will change only if the intended behaviour of the code changes -- if the revision is just a bug fix, they should not change.

Comments in the change log should describe what changes were made in this revision.

Corollary: Avoid putting revision numbers/dates and the name(s) of the programmer who made the changes in the code comments. (Thanks to both Jonathans.)

Goodhumored

I have been struggling to put that thought into words. – Hawkie

Also comments in the change log can't be changed but comments can be changed in the code by anyone at any time. Therefore any dates, names or revisions information should not be in the code. – Basion

I don't always agree on dates. If the bug is related to a workaround for a bug in a compiler, then it is helpful to have the platform, compiler version, and date in the comment explaining the hack. Then, 5-10 years later, you can review the code and remove the hack with more confidence. – Florencia

@Jonathan Leffler: I agree -- if the date refers to an external object, then it's part of "the intended behaviour" of the code and should be documented in code comments. – Goodhumored

I've updated the post to hopefully be clearer on this. (In the same way, you are allowed to include programmer names in code comments if it makes sense to do so, provided you're not giving the name of the programmer who made the change for that reason alone.) – Goodhumored

Answer 2

Don't clutter your code with comments that explain changes. That's just one more thing that needs to be maintained and probably won't be consistently, leading to more errors and more changes. Use the source control comment feature for what it is intended.

If you need to explain why something was done a certain way in comments in your code, that's fine. As long as it isn't required for every change. That leads to clutter comments like

// fixed bug #3365

Beware

Changed the question on you a little sorry. – Hawkie

Answer 3

Arguably. If you change the code but don't update the comment then comments get out of date. I'm a huge stickler for this sort of thing and I forget to update comments more often than I'd like to admit. But the description of the change is (or at least should be) never wrong.

Wan

Changed the question on you sorry. – Hawkie

Answer 4

Not in my opinion. Code should be commented such that you can easily read the code. This is even more necessary for code that had a bug which was fixed.

Both places should be well commented and it is probable that they will contain duplicate descriptions. However they are both used for different reasons. When you are backtracking through source control it is usually to track down how an issue was introduced. Having good comments can make this process much easier. Code comments allow you to work through the code to try and find the current bug or add the next feature.

They should be doing both and understand why it is important.

Cleaning

You would think they would want to comment the code more because they interact less with the source control system. The mere act of making them give clear details in the changelog is making their habits bad. – Hawkie

Changed the question on you a little bit. – Hawkie

Answer 5

Both the comments server different purpose. The code comments are to illustrate and explain what the piece of code does, how it works, what it expects and what it returns. Also the exceptional conditions that can arise.

The check-in comments are more to inform what changes you have made and the reasons for the change.

Underslung

Answer 6

Dont know if you use annotation tools, Some IDE's like eclipse integrate well with CVS and show you exactly which line was modified when and by whom if you use the cvs annotation tool.

Lubbi

Tools can help you vote. Unfortunately I would need many tools to cover all the cases. – Hawkie