Comment the interface, implementation or both?

Question

I imagine that we all (when we can be bothered!) comment our interfaces. e.g.

/// <summary>
/// Foo Interface
/// </summary>
public interface Foo
{
    /// <summary>
    /// Will 'bar'
    /// </summary>
    /// <param name="wibble">Wibble factor</param>
    void Bar(string wibble);
}

Do you also comment the implementation (which may also be provided to clients, e.g. as part of a a library)? If so how do you manage keeping the two in sync? Or do you just add a 'See interface for documentation' comment?

Answer 1

As a general rule, I use the same DRY (Don't Repeat Yourself) principle as with code:

• on interface, document the interface
• on implementation, document the implementation specifics

Java specific: when documenting the implementation, use {@inheritDoc} tag to "include" javadocs from the interface.

For more information:

• Official javadoc documentation
• Some unofficial advice.

Answer 2

C# usage:

Interface can look like this:

    /// <summary>
    /// Helper class to access various properties for the current site.
    /// </summary>
    public interface ISiteHelper
    {
        /// <summary>
        /// Gets the site id of the current site
        /// </summary>
        /// <returns>The site id.</returns>
        int GetSiteID();
    }
}

Implementation can look like this:

/// <inheritdoc />
public class SiteHelper: ISiteHelper
{
    public int GetSiteID()
    {
        return CommonRepository.GetSiteID();
    }
}

Official reference for <inheritdoc />: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags#inheritdoc

Answer 3

The interface only. Commenting both is duplication and it's likely that the two sets of comments will eventually get out of sync if the code changes. Comment the implementation with "implements MyInterface"... Things like Doxygen will generate docs that include the derived docs into the docs for the implementation anyway (if you set them up correctly).

Answer 4

If you use the GhostDoc addin, it updates the implementation with the comment from the interface when you right click and select "Document This" on the method.

Answer 5

For C# it depends IMO: If you use explicit interface implementations, then I wouldn't document the implementation.

However if you implement the interface directly and expose the members of the interface with your object then these methods must be documented too.

As Nath said, you can use GhostDoc to automatically insert the documentation of an interface into the implementation. I mapped the Document This command to the Ctrl+Shift+D shortcut and its one of the keystrokes I almost automatically press. I believe ReSharper also has the option to insert the documentation of the interface, when it implements the methods for you.

Answer 6

Commenting the interface should be enough documentation to figure out how to use the actual implementation. The only time that I would add comments to the implementation is if it has private functions that were inserted to satisfy the interface, however they would be internal only comments and would not be seen in documentation online or available to clients.

Implementations are just that, as long as they conform to the interface there is no need to document them separately.

Answer 7

We just comment the interface, comments are so easy to get out of sync with either the derived or base class/interface that's it's nice to have it in just one place.

Although it looks like @Nath maybe suggesting an automated documentation tool that helps keep things together (sounds cool if you use that). Here at WhereIWorkAndYouDontCare the comments are for dev so a single place in the code is preferred

Answer 8

You can certainly comment both but then you have the problem of maintaining both (as previously mentioned). However, in this day and age is any consuming code really not going to be using IoC/DI and not use the interface? Given this if you only want to bother commenting one I would strongly suggest commenting the interface. This way the consumer of your code will more than likely get the nice intellisense hints.

Answer 9

I created a tool that post-processes the XML documentation files to add support for the <inheritdoc/> tag.

While it doesn't help with Intellisense in source code, it does allow the modified XML documentation files to be included in a NuGet package and therefore works with Intellisense in referenced NuGet packages.

It's at www.inheritdoc.io (free version available).