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.

Motivation

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.

Documentation/commentary technique

Code comments

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

// comment

style to "comment out" code (In Visual Studio, the short key is

Ctrl-K U

, in SharpDevelop it's

Alt+/

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

/// <summary>
/// This class...
/// </summary>

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

<summary>

,

<param>

or

<exception>

. 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

<code>

,

<list>

or

<para>

.

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.

Usage targets

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

Class comments are the comments written on top of a class:

/// <summary>
/// This class represents a generic parser for evaluating
/// arithmetic expressions.
/// </summary>
/// <remarks>
/// The parser works on a <see cref="string"/> object with an
/// arithmetic expression and transforms it into a syntax tree
/// which consists of <see cref="SyntaxTreeNode"/> objects.
/// The grammar this parser uses is documented <a href="...">here</a>.
/// </remarks>
public class ExpressionParser
{
  [...]
}

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:

/// <summary>
/// Class for parsing expressions.
/// </summary>
public class ExpressionParser

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

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:

/// <summary>
/// Executes the expression parser on the specified
/// <paramref name="expression"/>, and returns a syntax
/// tree consisting of <see cref="SyntaxTreeNode"/> instances.
/// </summary>
/// <param name="expression">Arithmetic expression to be
/// parsed. For a format description, see the class
/// documentation/see here...</param>
/// <exception cref="ParseException">If the specified
/// <paramref name="expression"/> is empty or if it has the
/// wrong format.</exception>
/// <returns>
/// Syntax tree consisting of <see cref="SyntaxTreeNode"/>
/// instances. Every sub-expression, operator and value has its
/// own tree node. Inline comments, which have been parsed out
/// of /* ... */ constructs will be attached to
/// <see cref="SyntaxTreeNode.Properties"/> of the tree nodes.
/// </returns>
public static SyntaxTreeNode ExpressionParser.Parse(string expression)
{
  [...]
}

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:

/// <summary>
/// Switches the skin.
/// </summary>
/// <param name="skin">The skin.</param>
public void SwitchSkin(string skin)
{
  [...]
}

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.

Code comments

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.

int i = BracketHelper.FindClosingBracket(expression, bracketStart);
if (i == -1)
  return;
i += 1; // Skip the closing bracket
[...]

The code itself reveals, HOW something is done, good comments mostly say WHY. Compare it with the following, bad example:

Useless code comment:

int i = BracketHelper.FindClosingBracket(expression, bracketStart);
if (i == -1)
  return;
i += 1; // Increase i by 1
[...]

The situations, where only repeating the code in words helps understanding it, are very rare.

Summary

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