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.