CS100M Fall 2000
MATLAB Commenting & Style
Niranjan Nagarajan 

General Commenting Style for Functions:

Since we tend to think of functions as black boxes, its behavious should
be clear to a user if we clearly specify the inputs to and the outputs
from a function (the details of implementation of the function should not
matter.) One formal way of doing this is by specifying "Pre-conditions"
and "Post-conditions" for a function. Essentially pre-conditions specify
the meaning of each of the input arguments and they also specify what
kinds of data they can contain. Pre-conditions also specify additional
constraints regarding when the function can be called. Post-conditions
specify what values are gauranteed to be in the output arguments and in
what format. They also specify any side-effects that the function might
have, like input/output interaction with the user, plotting data etc.

What does this mean in terms of Matlab commenting:

1) Write the H1 comment line as before. 
2) In the comment lines that follow, specify the meaning of the input 
   parameters, taking care to mention if they need to be strings, doubles,
   matrices etc.
3) Finally, clearly specify what values the function puts into output
   arguments and any other I/O, plotting related work that the function
   does.