Comments in Code

Work on comments. I say this not for me although I am definately a consumer of your comments. I say this for you. I am sure you do not start and finish your lab is one sitting and in fact probably are intererupted literally hundreds of times between the time you start the lab and the time you finish the lab, Comments are the best way to help you get back up to speed as quickly as possible. Also, at some point in the future, assuming you stay in the software work, you will have one of the "ah-ha" I remember doing something like that back in college and try to find that code. Comments will make the difference then also.

I offer these guidelines as a basis for comments I am expecting in your code.

• Add a comment at the beginning of the main form, or file containing the main function, declaring the overall purpose of program and the basic steps you plan on taking to accomplish the task. Include a list of all modules and forms included in the project. This is where I look to get a good overview of your assignment or better yet, a good first impression of your assignment. This comment block should include the following:
  • Program Name:
  • Your Name:
  • Course:
  • Date:
  • Program Requirements:
  • Program Design:
  • Things you what me to know before I grade your work:
• Add comments at the beginning of each function / sub procedure to describe the purpose of the function / sub-procedure and the basic logic, flow of control, you intend to use. For example, a routine to convert a user input value for liters and then convert it to gallons and output the result might look like the following:
   
  in Visual Basic:
   
  '-----------------------------------------------------
  ' convertLitersToGallons
  '
  ' convert liters to gallons
  ' steps:
  ' 1. prompt user for liters input, if required
  ' 2. confirm valid input
  ' 3. convert to gallons
  ' 4. output / return answer
  '
  ' params:
  '  liters - the number of liters to convert to gallons
  '
  ' return
  ' nbr of gallons as a double
  '-------------------------------------------------------
  Function convertLitersToGallons(ByVal liters as Double) as Double
   
  or in C++:
   
  //-----------------------------------------------------
  // convertLitersToGallons
  //
  // convert liters to gallons
  // steps:
  // 1. prompt user for liters input, if required
  // 2. confirm valid input
  // 3. convert to gallons
  // 4. output / return answer
  //
  // params:
  //  liters - the number of liters to convert to gallons
  //
  // return:
  // number of gallons as a double
  //-------------------------------------------------------
  double convertLitersToGallons(double liters)
   
  or in C#:
   
  ///-----------------------------------------------------
  /// <summary>
  /// convertLitersToGallons
  ///
  /// convert liters to gallons
  /// steps:
  /// 1. prompt user for liters input, if required
  /// 2. confirm valid input
  /// 3. convert to gallons
  /// 4. output / return answer
  ///
  /// </summary>
  /// <param name>liters - number of liters to convert</param>
  ///
  /// <returns>number of gallons as a double</returns>
  ///-------------------------------------------------------
  private double convertLitersToGallons(double liters)
   
  or in Java:
   
  /**
  * convertLitersToGallons - convert liters to gallons using the following steps:
  * 1. prompt user for liters input, if required
  * 2. confirm valid input
  * 3. convert to gallons
  * 4. output / return answer
  *
  * @param liters the number of liters to convert
  *
  * @return  number of gallons as a double
  */
  double convertLitersToGallons(double liters)
   
  or in Ada:
   
  -----------------------------------------------------
  -- convertLitersToGallons
  --
  -- convert liters to gallons
  -- steps:
  -- 1. prompt user for liters input, if required
  -- 2. confirm valid input
  -- 3. convert to gallons
  -- 4. output / return answer
  --
  -- params:
  -- liters - the number of liters to convert
  --
  -- return
  -- number of gallons as a double
  -------------------------------------------------------
  function convertLitersToGallons(float liters) return float
   
  
• Add a comment after each variable declaration to explain what this variable will be used for, i.e.,
   
  in Visual Basic:
   
  

  	Dim i as integer      ' loop index counter
   
  
  	

  or in C++ or Java:
   
  

  	int  i;        // loop index counter
   
  
  	

  or in Ada:
   
  

  	i:  integer;  -- loop index counter
   
  
  	

  These comments should never preclude you from using self-describing variable names and in fact if the variable name is indeed self-describing, I would believe no comment is necessary. For example,
   
  

  	Dim nTotalWordCount as integer
   
  
  	

  or in C++ or Java:
   
  

  	int  nTotalWordCount;
   
  
  	

  or in Ada:
   
  

  	nTotalWordCount:  integer;
   
  
  	

  need no further comment.

• Add sufficient comments throughout the code to describe the logic used in this code. DO NOT simply repeat what the code already states. By this I mean, the comment "calculate total from max and nbr" for the statement iTotal = iMax * iNbr; is meaningless. Whereas a comment as to WHY total is calculated from max and nbr is meaningful.

• Always place comments on separate lines indented at least as far as the code they are commenting on, if not one level of indentation more. This makes it much easier to read and modify the comments as the program matures. The only possible exception to this rule is the commenting of variable declarations mentioned above.
• Try to get in the habit of writing larger comment blocks instead of many one line comments. Readability starts to suffer when the code becomes a sequence of comment line, code line, comment line, code, etc. But say five comment lines followed by ten code lines would make the code much easier to read and modify the comments as the program matures.