Comments

The purpose of comments is to add information to the code. Typical uses for comments are to explain usage, provide reference information, to justify decisions, to describe limitations, to mention needed improvements. Experience indicates that it is better to write comments at the same time as the code rather than to intend to add comments later.

Comments cannot justify poorly written code

Comments cannot make up for code lacking appropriate name choices and an explicit logical structure. Such code should be rewritten. Steve McConnell: “Improve the code and then document it to make it even clearer.”

Comments should agree with the code, but do more than just restate the code

A bad or useless comment just gets in the way of the reader. N. Schryer: “If the code and the comments disagree, then both are probably wrong.” It is usually more important for the comment to address why or how rather than what.

Comments should be easy to read

There should be a space between the % and the comment text. Comments should start with an upper case letter and end with a period.

Comments should usually have the same indentation as the statements referred to

This is to avoid having the comments break the layout of the program. End of line comments tend to be cryptic and should be avoided except for constant definitions.

Function header comments should support the use of help and lookfor

help prints the first contiguous block of comment lines from the file. Make it helpful.

lookfor searches the first comment line of all m-files on the path. Try to include likely search words in this line.

Function header comments should discuss any special requirements for the input arguments

The user will need to know if the input needs to be expressed in particular units or is a particular type of array.

% ejectionFraction must be between 0 and 1, not a percentage.

% elapsedTimeSeconds must be one dimensional.

Function header comments should describe any side effects

Side effects are actions of a function other than assignment of the output variables. A common example is plot generation. Descriptions of these side effects should be included in the header comments so that they appear in the help printout.

In general the last function header comment should restate the function line

This allows the user to glance at the help printout and see the input and output argument usage.

Writing the function name using uppercase in the function header is controversial

This is a MathWorks practice, which is intended to make the function name prominent. Many other authors do not follow this practice. Its disadvantage is that in code the function name should usually be in lower case. Newer versions of MATLAB will make an all-caps function name lowercase and bold in the help printout.

Avoid clutter in the help printout of the function header

It is common to include copyright lines and change history in comments near the beginning of a function file. There should be a blank line between the header comments and these comments so that they are not displayed in response to help.

All comments should be written in English

In an international environment, English is the preferred language.