Connecting Tech Pros Worldwide Forums | Help | Site Map

Commenting during debugging, in C

Member
 
Join Date: Jul 2008
Posts: 62
#1: Jul 21 '08
Hello - I am new to this and started a new job; and for now I am in charge of debugging everyone's C code.

Can you please tell me the proper way to comment during this debugging process? Should I comment on every change I make, or just important ones? What is the programming etiquette?

thanks!

Member
 
Join Date: Jul 2008
Posts: 53
#2: Jul 23 '08

re: Commenting during debugging, in C


I have worked in several c/c++ roles. In each of them, every piece of code went through a formal review process on creation, and any problems were referred back to the engineer who had proposed the code change.
If a bug was found beyond this stage, it was usually reported as a known problem (which needed to be fixed with varying urgency), and the formal process would begin again to write, review and refine the code.
In addition to this, version control was used to track changes, so that it was clear who had made what change.

With more specific regard to your question, consider yourself part of the review stage. Your job is to find problems, but not necessarily fix them. If you are expected to fix them, there should be VC-ing procedures in place that can track who has modified code, and what they have modified. This being the case, my suggestion would be comment anything that isn't clear....
if you change a variable name for clarity (or spelling), this is probably evident in a check between old and new version, and may no need a comment. If you make a logic change (however small), always conside - will someone (not necessarily uyou) be able to understand what this code used to do, what this code now does and why this change was necessary.
Assuming you have license to fix problems you find without going through any Quality Control process, I would take the same (or very similar) approach to commenting areas you change as I would to commenting any other code. I have experienced projects where you are required to clearly comment all post-Release changes (or patches) eg:
Expand|Select|Wrap|Line Numbers
  1. /******* Change Request 1506 ****/
  2. int j=3; /* Changed from 4 because .... */
  3. /****** End  Change Request 1506 ****/
  4.  
Hope (some of, at least) this helps!!
gpraghuram's Avatar
Expert
 
Join Date: Mar 2007
Location: Chennai
Posts: 1,258
#3: Jul 23 '08

re: Commenting during debugging, in C


Its better if you comment every change you make with a proper Comment.

But dont give too much comments which may make the code cluttered.


raghu
Reply