Documentation and comments

Add documentation to every function or class you contribute to the Two!Ears model.

Class headers

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).

Function headers

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 uses the 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.

Comments

  • Add comments into your code at places that are not self explanatory.
  • If you implement a particular equation from a paper, please add a citation of that paper and equation as a comment.
  • Avoid meaningless comments like ildValue = 10; % ild value

License

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

Author

We have lots of different authors that might also contribute to lots of different files. Hence, we mention no single author in the individual files. The contributions of the authors could be seen in the git commit history.

Instead, we state the authors under the point Credits in the main README.md file of the single repositories.

An exception to this case is the usage of code from a person, that is not part of the Two!Ears project. In that case the author should be properly cited in the code.

Versioning

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.