To be consistent in the code documentation for MediaPortal we should follow a set of documentation guidelines. If you are a developer please review these guidelines to ensure consistency throughout the MediaPortal project.
MediaPortal is an open-source project. This means many people are reading and working with the code.
When new classes get written, a programmer has a special idea how it should work: He knows, what the class should achieve, and what it shouldn't. People, who read the code later, don't know this idea. It can be hard to understand the meaning of a class, if this first design idea gets lost or if it isn't present in the current reader's head. It is even worse if someone wants to debug or change code, if he doesn't know the actual meaning of the code ("Is it just a bug in the code, or is the current behaviour intended by design?"). This sometimes leads to changes at the wrong place, done non-compliant with the actual idea behind the code.
It is very important to know the contract of a class or method. Without a knowledge about that contract, code doesn't scale. No developer should be forced to know the implementation of a method to use it; the documentation must be enough to understand a class or method.
Writing documentation can often be boring or even annoying. But if you take the time to document your code, you have the matchless chance of thinking about your code once again. Many programming defects become obvious by once again thinking of the big picture.
Comments must be indented to the indent level of the code when they are used for code documentation.
Commented out code MUST be preceded by a single-line comment giving the reason, why the code was commented out. You may also write your name and a date here.
A rule of thumb says that generally, the length of a comment should not exceed the length of the code explained, as this is an indication of too complicated code.
You should use the
style to "comment out" code (In Visual Studio, the short key is
, in SharpDevelop it's
). This will comment out the current line or the current selection.
C# code documentation
In the .net framework, Microsoft has introduced a documentation generation system based on XML comments. These comments are formally single line C# comments containing XML tags. They follow this pattern for single line comments:
All lines must be preceded by three slashes to be accepted as XML comment lines. Tags fall into two categories:
- Documentation items
- Formatting / Referencing
The first category contains tags like
. These represent items that represent the elements of a program's API which must be documented for the program to be useful to other programmers. These tags usually have attributes such as name or cref. These attributes are checked by the compiler, so they should be valid. The latter category governs the layout of the documentation, using tags such as
Documentation can then be generated using the 'documentation' item in the #develop 'build' menu. The documentation generated is in HTML Help format.
For a fuller explanation of XML comments see the Microsoft .net framework SDK documentation. For information on commenting best practice and further issues related to commenting, see the technical note 'The fine Art of Commenting'.
Please fill out member summary comments, if the documented member can be understood wrong. This helps other developers to perfectly understand the meaning of methods and properties.
Comment your code wherever it adds a clearer understanding. Keep in mind that this is an open source project and other developers cannot read your mind.
Important: How and what should be documented?
Lets come to the really exciting questions of documenting. How can a comment make my code better? To motivate the guidelines which I'll present later, lets take a look at the typical usages of source code documentation.
Comments from the source code will be typically visible in those situations:
- In the code itself
- In ToolTips shown by an IDE, when you move the mouse cursor over an identifier which was documented at another place
- In generated online source code documentation
So documenting the code can be perfect, if we consider all those typical usages when writing comments.
What to write where?
Class comments are the comments written on top of a class:
First, this documentation is useful in the code itself, because gives the reader an overview of the class and a specification. Second, The user of the class will learn if this class will fit his needs, if use it and how to use it. The guy enhancing functionality can use it to check, if the new functionality fits into the original design.
The documentation is also useful in the IDE ToolTips, off course.
The generated online documentation profits because this comment gives an overview, a detailed description and it links to other related resources.
Class comments will be visible in all overviews generated from the code. It should contain more information than that the class name already gives. Don't only rewrite the class name, like in the next example.
Useless class comment:
So what constitutes a good class comment? Here are some general suggestions, which may be important for some classes, but which don't need to be used for every class:
- Summary part:
- (Exact) purpose of the class
- Mark-off of the class in respect to other similar classes
- Remarks part:
- Longer explanation of the purpose of the class, what does it do, what doesn't it do?
- How can it be used (examples?)
- Rules to be followed when using this class
- Invariants which are always true during the lifetime of an instance
- Which other classes are related to this class?
- Threading safety
Member comments are the comments written on top of class members. You can comment all types of members, but not for all types the documentation is useful the same. In general, all non-private members should be documented, if the comment gives the reader additional information, like this:
This documentation is useful in the code itself, because it states the specification of the method directly in the code. This means, the writer of the method code can easily watch it again. On top of methods, we document WHAT the method will do. From this docs, the developer will be reminded of all documented properties his code has to fulfill. The reader of the code at the other hand can easily understand WHAT the code does without the need to understand HOW it does it. The guy debugging the code can easily compare the real behaviour of the code with the documented behaviour, and so he has a chance to decide if an erroneous behaviour is originated at this method or if it is because the input values were wrong, for example.
The IDE ToolTips and the generated online documentation profit because of the same reasons like said above.
Be honest: Would you have documented the Parse method like this? Please take some time to think about the added value provided by this documentation. Please compare it to this awful example, which I really found in MediaPortal 2 code!
Really useless method comment:
It is even better to write NO comments instead of such useless ones. If a comment cannot clarify anything for the reader, it is only a ballast and should be avoided.
In contrast to XML documentation comments above classes and members, code comments are neither visible in IDE ToolTips nor in any generated documentation. They are only visible to people looking directly into the code. So don't repeat what can be seen in the code but add useful information where needed. Code comments should tell the reader, WHY something is done in a special way.
The code itself reveals, HOW something is done, good comments mostly say WHY. Compare it with the following, bad example:
Useless code comment:
The situations, where only repeating the code in words helps understanding it, are very rare.
- Code documentation helps different people in different situations. It helps the primary developer as well as the guy possibly refactoring the code later.
- On top of methods, say exactly WHAT the method will do.
- In the code itself, say WHY the code is written like this.
- Normally, it is not necessary to write HOW the code works - this can mostly be seen in the code itself.
This page has no comments.