Comment the interface, implementation or both?

c# java comments interface

42,595

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

Solution 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
{
    /// <inheritdoc />
    public int GetSiteID()
    {
        return CommonRepository.GetSiteID();
    }
}

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

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

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

View more solutions

42,595

Author by

ng5000

Updated on July 08, 2022

Comments

ng5000 almost 2 years
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?

Thanks
- bytedev almost 5 years
  
  A duplicate snuck through here: stackoverflow.com/questions/1875440/…
Ellis Shen about 15 years

Not automated, requires user action, unfortunately.
mcherm almost 14 years

Wow... I had no idea {@inheritDoc} existed either! I'll use it regularly from today on.
Daniel A.A. Pelsmaeker almost 12 years

For C#, you can use <inheritdoc />, which is supported by SandCastle. (More info...)
SondreB almost 9 years

Properties and other elements within an inherited class does not show the XML documentation in the tooltip when only specified on the interface. For external use of the same class, it is visible. This might be a bug with Visual Studio 2015.
Marek Halmo over 7 years

You don't have to use @inheritDoc in Eclipse because the IDE will automatically pull comments from interface even if you use a variable of the type of implementation class (which is a wrong practice as you should always use interface for the variable type!)
Olly over 6 years

Note that <inheritdoc /> is supported by Sandcastle Help File Builder too, and is documented here: ewsoftware.github.io/XMLCommentsGuide/html/…. Just spotted that this was also mentioned above.
weir about 6 years

Here's an updated version of the link @Virtlink provided for the Sandcastle/SHFB inheritdoc page: ewsoftware.github.io/XMLCommentsGuide/html/…
Mog0 about 4 years

<inheritdoc /> seems to work with Visual Studio 2019 in C#. If you use it the intellisense will display the comment from the interface.
Wouter over 2 years

This only works for methods. InheritDoc on the class will show the documentation for Object.