Comenta la interfaz, implementación o ambos?

Me imagino que todos (¡cuando podemos molestarnos!) Comentamos nuestras interfaces. p.ej

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

¿También comenta la implementación (que también se puede proporcionar a los clientes, por ejemplo, como parte de una biblioteca)? Si es así, ¿cómo logras mantener los dos sincronizados? ¿O simplemente agrega el comentario 'Ver interfaz para documentación'?

Gracias

Como regla general, utilizo el mismo principio DRY (Don't Repeat Yourself) que con el código:

• en la interfaz, documente la interfaz
• en la implementación, documente los detalles de la implementación

Específico de Java : al documentar la implementación, use la etiqueta {@inheritDoc} para "incluir" javadocs desde la interfaz.

Para más información:

• Documentación oficial de javadoc
• Algunos consejos no oficiales .

Si usa el complemento GhostDoc , actualiza la implementación con el comentario de la interfaz cuando hace clic derecho y selecciona "Documentar esto" en el método.

Para C #, depende de la OMI: si usa implementaciones de interfaz explícitas, entonces no documentaría la implementación.

Sin embargo, si implementa la interfaz directamente y expone los miembros de la interfaz con su objeto, estos métodos también deben documentarse.

Como dijo Nath, puede usar GhostDoc para insertar automáticamente la documentación de una interfaz en la implementación. Mapeé el documento Este comando al atajo Ctrl + Shift + D y es una de las teclas que presiono casi automáticamente. Creo que ReSharper también tiene la opción de insertar la documentación de la interfaz, cuando implementa los métodos por usted.

La interfaz solamente. Comentar ambos es una duplicación y es probable que los dos conjuntos de comentarios eventualmente se desincronicen si el código cambia. Comente la implementación con "implementa MyInterface" ... Cosas como Doxygen generará documentos que incluyan los documentos derivados en los documentos para la implementación de todos modos (si los configura correctamente).

Simplemente comentamos la interfaz, los comentarios son tan fáciles de sincronizar con la interfaz / clase derivada o base que es bueno tenerla en un solo lugar.

Aunque parece que @Nath quizás sugiera una herramienta de documentación automatizada que ayude a mantener las cosas juntas (suena genial si la usa). Aquí en WhereIWorkAndYouDontCare los comentarios son para desarrolladores, por lo que se prefiere un solo lugar en el código

Comentar la interfaz debería ser suficiente documentación para descubrir cómo usar la implementación real. El único momento en que agregaría comentarios a la implementación es si tiene funciones privadas que se insertaron para satisfacer la interfaz, sin embargo, serían comentarios internos y no se verían en la documentación en línea ni estarán disponibles para los clientes.

Las implementaciones son solo eso, siempre que se ajusten a la interfaz, no es necesario documentarlas por separado.

Creé una herramienta que procesa posteriormente los archivos de documentación XML para agregar soporte para la etiqueta <heredardoc />.

Si bien no ayuda con Intellisense en el código fuente, sí permite que los archivos de documentación XML modificados se incluyan en un paquete NuGet y, por lo tanto, funciona con Intellisense en los paquetes NuGet referenciados.

Está en www.inheritdoc.io (versión gratuita disponible).

Ciertamente puede comentar ambos, pero luego tiene el problema de mantener ambos (como se mencionó anteriormente). Sin embargo, en estos tiempos ¿algún código consumidor realmente no usará IoC / DI y no usará la interfaz? Teniendo esto en cuenta si solo desea molestarse en comentar uno, le sugiero que comente la interfaz. De esta forma, es muy probable que el consumidor de su código obtenga las buenas sugerencias de inteligencia.

Uso de C #:

La interfaz puede verse así:

    /// <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();
    }
}

La implementación puede verse así:

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