Loren on the Art of MATLAB

Turn ideas into MATLAB

Note

Loren on the Art of MATLAB has been archived and will not be updated.

Commenting Code

Posted by Loren Shure,

5 views (last 30 days)  |   Likes   |   15 comments

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.
  • 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


Category: 
Best Practice,
Less Used Functionality
  • print

See Also