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.
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.
Documentation
Formal documentation
To be useful documentation should include a readable description of what the code is supposed to
do (Requirements), how it works (Design), which functions it depends on and how it is used by
other code (Interfaces), and how it is tested. For extra credit, the documentation can include a
discussion of alternative solutions and suggestions for extensions or maintenance.
Dick Brandon: “Documentation is like sex; when it's good, it's very, very good, and when it's bad,
it's better than nothing.”
Consider writing the documentation first.
Some programmers believe that the best approach is “Code first and answer questions later.”
Through experience most of us learn that developing a design and then implementing it leads to a
much more satisfactory result.
Development projects are almost never completed on schedule. If documentation and testing are
left for last, they will get cut short. Writing the documentation first assures that it gets done and
will probably reduce development time.
Changes.
The professional way to manage and document code changes is to use a source control tool. For
very simple projects, adding change history comments to the function files is certainly better than
nothing.
% 24 November 1971, D.B. Cooper, exit conditions modified.
References
The Practice of Programming, Brian Kernighan and Rob Pike
The Pragmatic Programmer, Andrew Hunt, David Thomas and Ward Cunningham