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.

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