Documentation and comments¶
Add documentation to every function or class you contribute to the Two!Ears model.
Class headers should contain a brief description of what the class is doing and
probably contain a few examples on how to use the methods that the class provides.
A good example is the description of the Gaussian-Mixture distribution class that
is provided by the Matlab Statistics Toolbox. Type
help gmdistribution in the
command window for more details.
%ClassName This class contains several fancy methods to solve problems that % are even more fancy. To create a fancy problem solving environment, % use the ClassName constructor. You can solve problems by running % ClassName.solveFancyProblems(fancyProblem). A fancy problem can be % specified as a Matlab cell-array, containing...
The class header does not need to contain a description of the class methods, as they should be properly documented in their own headers. Additionally, there is no need to put additional comments to the class properties, as long as they are properly named (see the section on naming conventions below).
It is a good idea to have a consistent function header in all Two!Ears functions,
this makes a much better impression and enhances the understanding if people
help function. They should look like the following:
%functionName This function is calculating fancy stuff1, not so fancy stuff2, % and provides you a nice solution. % % USAGE % outputParameter = functionName(inputParameter1) % outputParameter = functionName(inputParameter1,inputParameter2) % % INPUT PARAMETERS % inputParameter1 - description of inputParameter1 % inputParameter2 - description of inputParameter2 % % OUTPUT PARAMETERS % outputParameter - description of outputParameter % % DETAILS % Here, more details could be presented. But only, if really needed.
This means that we follow not the Matlab standard of writing the function name
in capital letter at the beginning
FUNCTIONNAME. This is not useful in our
case as we use CamelCase notation.
If a function comes with a different license (and only then) than the one
specified in the main
README.md of the single repositories the license has
to be stated in the function.
In order to avoid clutter with the
help command add an empty line between the
header and the license.
% OUTPUT PARAMETERS % outputParameter : description of outputParameter % LICENSE: license
If you don’t use a version control system you are maybe used to put changes with dates into the file header directly like
% 10.10.2014: Completely changed everything % 11.10.2014: Was not so good, undo changes
Since we are using git for versioning such lines should be deleted from the code.