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 centeras 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 06This 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 endThis 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
cx2 = R3-g2; % x coordinate of circle 2 centerThis 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:
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|
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: 220.127.116.11 $ % $Date: 2008/04/02 22:18:24 $ % % $Log: comments.html,v $ % Revision 18.104.22.168 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