We have been asked to add comments with start tags, end tags, description, solution etc for each change that we make to the code as part of fixing a bug / implementing a CR.
My concern is, does this provide any added value? As it is, we have all the details in the Version control history, which will help us to track each and every change?
But my leads are insisting on having the comments as a "good" programming practice. One of their argument is when a CR has to be de-scoped/changed, it would be cumbersome if comments are not there.
Considering that the changes would be largely in between code, would it really help to add comments for each and every change we make? Shouldn't we leave it to the version control?
Best Answer
You are absolutely right. Tracking changes is the job for your version control system. Every time you do a commit you should write a commit message explaining what was done, and referencing your bug-tracking system if this is a bug fix. Putting a comment in the code saying
every time you fix a bug will quickly render your code unreadable and unmaintainable. It will also result in duplicating the same information in two places, which will make the mess even worse.
Comments should not be used for bug tracking and they also should not describe what your code is doing. They should explain why you are doing X, or why you are doing X in this particular way. If you feel the need to write a comment explaining what a block of code is doing, that is a code smell which indicates that you should refactor this block into a function with a descriptive name.
So instead of
you might have a comment that says
or