All too frequently, for whatever reason, developers don’t take the time to write good comments when “checking in” their code changes. I know, as I’ve been guilty of that behavior in the past.
At the time of “check-in” comments are never useful, but just another thing to do. However comments can be extremely helpful 3 weeks, a month or two years from now. Well written comments allow you to find changes made to the code base without having to interrogate multiple files in multiple baselines.
Over my years as a developer, I picked up different tips and tricks from my peers. One habit I picked up from another developer is to write comments in a parallel file before making any code changes. For example, if you are working on widget.java, the parallel file containing comments would be widget.java.comment. The comments in this file would be clear and concise and would be based on the feature or bug fix being working on. This file also acts as a reminder of what work was to be done in what file.
When your work is finished and ready to “check-in”, you can feed the comments files to the “check-in” command. This makes the whole process simple and scriptable which is an added benefit.
The next time you start working on a bug fix or new feature, consider this approach. However you enter comments, take the time when you’re running an AccuRev add, defunct, move, keep, promote… to provide a clear, concise and useful comment. The person you end up helping in the future may be yourself.