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.

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

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