20-ENFD-112-00x
Engineering Fundamentals of Programming
Basic Programming Concepts and Modeling for Engineers

MATLAB Program Comment Guide
Commenting well is an extremely important aspect of MATLAB programming. Well commented code allows a user (even the writer) to figure out what the program is intending to do, what the input parameters accepted by the program are (that is, their format, range and meaning), what the expected output is, and how the output is derived from the input. Without proper comments programs become so hard to maintain that they can become useless, and eventually may be discarded - someone's hard work down the drain! These notes will serve as a guide to commenting code for this course. We will state what a comment is, what the format of a comment is, how we expect you to use comments, and what the programming community says about comments.

Comment format in MATLAB
    A comment is a string of characters following a % character. For example, the following is a comment: 
 
   % PlotCircle_5.m: Plot two circles (circles 1 and 3 with radii R1, R3)
Comments are for humans only. MATLAB ignores any characters on a line including and following a % character. Thus, MATLAB processes the line 
 
   cx2 = R3-g2; % x coordinate of circle 2 center
as though it is 
 
   cx2 = R3-g2;

Types of Comments
    Block Comments: Comments that fully occupy one or more consecutive lines in the program. These comments are intended to convey the intentions of several lines of code (that is, a block of code - hence the name block comments). The block of code the comment descibes may even be the entire program. Block comments do not describe or state low-level actions such as the fact that a variable is given the value 50. The following is an example of a suitable block comment that would be placed before anything else in an acceptable lab 2 solution. 
   % PlotCircle_5.m:   Plot two circles (circles 1 and 3 with radii R1, R3) 
   %       tangent to each other at the origin with centers on the x axis 
   %       and a third circle (circle 2 with radius R2) tangent to and above 
   %       circles 1 and 3.
   % Input: Radii R1, R2, and R3 of three circles.  R1, R2, R3 are numbers.
   % Usage: Three prompts will be given, numbers are entered at eash prompt
   % Output: Plot of three tangent circles as above
   % For lab 2 - J. Franco, 8 Apr 06
This comment names the file the program is in (you may be surprised how important this is), gives a precise description of what the program is trying to do, states the three input parameters and their types, states how the program is to be used, and states the expected output. Such introductory comments should have this form but some lab solutions will require more detail and some less. In practice, intro comments also have a complete revision history which includes dates, name of person doing the revision, and descriptions of the revision. An example is presented at the end of this webpage.

The following is an example of a block comment that might appear before a block of code - the block is also shown: 

   % Schedule speaker 1 in consecutive periods in the same room until
   % its required limit is reached.  Then do the same for the other
   % speakers.  Wrap around to the next room when the last period is 
   % scheduled for that room.
   count = 1;
   i = 1;
   for j=1:nrms
      for k=1:nprds
         if i <= nspks
            x0(S(i,j,k),1) = 1;
            count = count+1;
            if count > reqd(i)
               i = i+1;
               count = 1;
            end
         end
      end
   end
This comment describes what the block is intending to do without stating details of how it is going to do it. Note: line comments (see below) have been removed from the block to focus attention on the block comment that is heading it.
    Line Comments: These are comments that occupy a portion of a line following a MATLAB statement. Such comments are intended to clarify the meaning of that line. The following is an example of a line comment: 
 
   cx2 = R3-g2; % x coordinate of circle 2 center
This comment states that the value of cx2 computed on this line will be the x coordinate of the center of a circle identified as circle number 2. Not all lines need to be commented - only a line that needs such clarification should be commented. For example, the lines of the following block do not need to be commented (however, I would expect to see a block comment before this block of code): 
   figure(2);
   mesh(t,v,wc2);
   xlabel('Temperature');
   ylabel('Wind Speed');
   zlabel('Wind Chill');
   title('Wind Chill Old');

Comments You Should Write
    Write comments to satisfy the following requirements:
  1. An introductory, multiline comment that states filename, author, lab assignment addressed, date, input (including specific parameters and types), output (plot, and/or console output) and function of the program.
  2. Before every meaningful block of code there should be a description of that block. For example, in lab 2 there is a block of code for computing the coordinates of the centers of the upper and lower circles and there should be a block comment indicating that.
  3. Behind every really important statement that needs clarification, there should be a comment clarifying that statement - so that a human can figure out what the statement is trying to do.
  4. Your comments should clarify, not confuse. If a proposed comment does not clarify, don't use it!

What Programmer's Say about Comments
    There is a lot of disagreement about comment writing. Some people (me, for example) believe that programs should be written so clearly in the first place that comments should be practically unnecessary. Unfortunatlely, whereas this principle may be applied to Java programs, it certainly cannot be applied to MATLAB programs - the extra power of MATLAB functions pretty much forces additional clarification via comments. Some people believe that the writer of code should have more comment lines than the code itself! Then there are all levels of middle ground. If you are interested in this discussion, and judging from class reaction you probably aren't, you might take a look at the Wikipedia article 
   http://en.wikipedia.org/wiki/Comment
and the external links available from it.

Example of Intro Block Comments
    This is adapted from a java distribution to minimize confusion. This is the intro to a very small program that performs a specific function in a very large project that aims to support an I-Wars tournament. 
   % Wealth.m                                           -*- Java -*-
   %    A class to encaspulate all the types of Wealth
   %
   % COPYRIGHT (C) 1998, Bradley M. Kuhn
   %
   % This program is free software; you can redistribute it and/or
   % modify it under the terms of the GNU General Public License as
   % published by the Free Software Foundation; either version 2 of
   % the License, or (at your option) any later version.
   %
   % This program is distributed in the hope that it will be useful,
   % but WITHOUT ANY WARRANTY; without even the implied warranty of
   % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   % GNU General Public License for more details.
   %
   % You should have received a copy of the GNU General Public License
   % along with this program; if not, write to the Free Software
   % Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
   %
   %
   % Written   :   Bradley M. Kuhn         University of Cincinnati
   %   By          
   %
   % Written   :   John Franco
   %   For         Special Topics: MATLAB Programming
   %               15-625-595-001, Fall 1998
   % RCS       :
   %
   % $Source: /home/franco/CVS/html/Courses/E112/html/Questions/comments.html,v $
   % $Revision: 1.1.1.1 $
   % $Date: 2008/04/02 22:18:24 $
   %
   % $Log: comments.html,v $
   % Revision 1.1.1.1  2008/04/02 22:18:24  franco
   %
   %
   % Revision 1.1  2004/01/22 04:50:56  cokane
   % Initial revision
   %
   % Revision 0.12  1998/12/15 05:56:01  bkuhn
   %   -- put files under the GPL
   %
   % Revision 0.11  1998/12/02 07:32:03  bkuhn
   %   -- moved so that Economy didn't need to be static in Wealth
   %
   % Revision 0.9  1998/11/30 08:12:45  bkuhn
   %   -- made it serializable
   %   # FIX ME:  That increaseHOlder() call probably shouldn't be there!
   %
   % Revision 0.8  1998/11/29 12:02:15  bkuhn
   %   # changed some types from int to long
   %
   % Revision 0.7  1998/11/25 04:44:38  bkuhn
   %   -- added getResourceNames() method so one can iterate over the
   %      resource names if needed
   %
   % Revision 0.6  1998/11/18 07:08:50  bkuhn
   %   -- fixed the functions that deal with holdings
   %   -- filled in the Resource implementations
   %   -- created synthesize
   %
   % Revision 0.5  1998/11/16 07:41:01  bkuhn
   %   -- set things up to use the new distribution stuff from Economy
   %   -- added getEconomy()
   %
   % Revision 0.4  1998/11/15 17:04:12  bkuhn
   %    # working with getting Economy working
   %
   % Revision 0.3  1998/11/13 10:55:42  bkuhn
   %   -- changed the way holdings is initialized
   %   -- began work on Economy and daily allotment
   %
   % Revision 0.2  1998/11/03 06:15:58  bkuhn