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.
- 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
Comments
To leave a comment, please click here to sign in to your MathWorks Account or create a new one.