NOTICE: Our Community is moving. Get more information.
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.
Dave, I add source code comments to code as I work in a format suitable for Doxygen, a tool that generates HTML help from the comments. This lets me update and refine the documentation over time along with the code, while keeping everything in one place. When a milestone is reached, before I run the AccuRev command I open a text editor, run a diff, and copy/paste the relevant comments to it. Then a few small formatting changes in the editor and I have a comment ready for AccuRev.
And yes, I do this for me. :)
Well that certainly is a best practice, to keep the code and documentation all in one place. When issuing an “accurev keep” or “accurev promote” command and being able to simply pull out the associated comment from the file is a tremendous time saver.
While working on many software projects the norm became to write module / function headers in a pseudo man(1) page format. During the build the man pages would be “harvested” and put into a man hierarchy. This had huge benefits for all the developers as they could run “man –s3 widget_get” to find out what this function did and its interface. Having the documentation and code together in the same file saved lots of time.