Loren on the Art of MATLAB

Turn ideas into MATLAB

Commenting Code

My thesis advisor wanted to cheerfully annihilate me one day many years ago when he was working with a program I wrote. I had a huge set of comments describing the program inputs and outputs, and all the ins and outs of using the program I could think of. Unfortunately for him, the final comment read like this:

   "Ignore all previous comments; they were for an earlier version of this program."

I have tried to be a better comment citizen ever since.

Contents

When to Comment

Here are some of my guidelines for when to insert comments. Note: I don't always follow my own advice!

Help

  • The H1 line -- the first help line in an M-file, following the function declaration, if the M-file is not a script.
  • The help body -- the first block of comments in the M-file, contiguous to the H1 line, stating the syntax and usage. This section may contain sections for Limitations, Examples, Class support, and See also references.

Functions

  • An H1 line for each subfunction. I don't, however, necessarily feel the same way about nested functions, depending on their usage. What do you think?
  • The final end statement of each function, if used, and certainly when nested functions are in the file.
  • In nested functions, when a variable is likely to be changed from code elsewhere in the file. This way, I am more likely to understand what I'm seeing when I debug.

Algorithms

  • A description of each logical chunk of code, especially when an algorithm has many steps.
  • Equivalent M-code or perhaps code in some other language, especially if some code is potentially very obscure or dense. An example might be to show the explicit for-loop equivalent code versus the vectorized expression.

Comment Tip

Block comments can be very useful for placing comments in the middle of a multi-line statement or expression in MATLAB. Sometimes I end up with a long list of properties I think I want to change in plot.

type hgComments
hgComments
% Base script to illustrate block comments.

t = pi:pi/20:5*pi;
sinc = sin(30*t)./t;
h = plot(t,sinc);
set(h,...
    'linestyle','--',...
    'color','m',...
    'marker','diamond',...
    'markersize',8,...
    'markerfacecolor','c',...
    'markeredgecolor','b'...
    )
    

If I try to just comment out the line setting the MarkerFaceColor property, I find that the editor shows me an mlint message.

dbtype hgCommentsBad
1     % Script to illustrate misuse of comments within a statement.
2     
3     t = pi:pi/20:5*pi;
4     sinc = sin(30*t)./t;
5     h = plot(t,sinc)
6     set(h,...
7         'linestyle','--',...
8         'color','m',...
9         'marker','diamond',...
10        'markersize',8,...
11    %    'markerfacecolor','c',...
12        'markeredgecolor','b'...
13        )
14        
info = mlint('hgCommentsBad');
info.message
ans =
Terminate statement with semicolon to suppress output.
ans =
There may be a parenthesis imbalance around here.
ans =
Terminate statement with semicolon to suppress output.
ans =
There may be a parenthesis imbalance around here.
try
    hgCommentsBad
catch
    l = lasterror();
    disp(l.message)
end
Error: File: H:\Documents\LOREN\MyJob\Art of MATLAB\hgCommentsBad.m Line: 11 Column: 31
Expression or statement is incorrect--possibly unbalanced (, {, or [.

Instead I can use block comments to achieve the goal of not setting the property in the middle of my list, without deleting the code, until I am sure that's the change I want.

dbtype hgCommentsGood
1     % Script to illustrate block comments.
2     
3     t = pi:pi/20:5*pi;
4     sinc = sin(30*t)./t;
5     h = plot(t,sinc);
6     set(h,...
7         'linestyle','--',...
8         'color','m',...
9         'marker','diamond',...
10        'markersize',8,...
11    %{
12        'markerfacecolor','c',...
13    %}
14        'markeredgecolor','b'...
15        )
16        
info = mlint('hgCommentsGood');
info.message
hgCommentsGood

Can you see yourself using block comments to help you with some of your programming tasks? Let me know.


Published with MATLAB® 7.3

|
  • print
  • send email

Comments

To leave a comment, please click here to sign in to your MathWorks Account or create a new one.