Having problems with your account or logging in?
A lot of changes are happening in the community right now. Some may affect you. READ MORE HERE

AccuRev Keep - Your Developers Moving Forward! AccuRev Admin’s Real Life Experiences // Comments on Comments

Micro Focus Frequent Contributor
Micro Focus Frequent Contributor
1 2 1,537

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.

2 Comments
bbuttolph Absent Member.
Absent Member.

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

Micro Focus Frequent Contributor
Micro Focus Frequent Contributor

Hello Brian,

 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.

Dave

The opinions expressed above are the personal opinions of the authors, not of Micro Focus. By using this site, you accept the Terms of Use and Rules of Participation. Certain versions of content ("Material") accessible here may contain branding from Hewlett-Packard Company (now HP Inc.) and Hewlett Packard Enterprise Company. As of September 1, 2017, the Material is now offered by Micro Focus, a separately owned and operated company. Any reference to the HP and Hewlett Packard Enterprise/HPE marks is historical in nature, and the HP and Hewlett Packard Enterprise/HPE marks are the property of their respective owners.