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

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.

Answer 2

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.

Answer 3

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.

Answer 4

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

Answer 5

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 6

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.