Comenta la interfaz, la implementación o ambas?

Question

Imagino que todos (cuando nos molestan) comenten 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 te las arreglas para mantener los dos sincronizados? ¿O simplemente agrega un comentario 'Ver interfaz para documentación'?

Gracias

Answer 1

un solo lugar en el código Como regla general, utilizo el mismo DRY (Do not Repeat Yourself) principio que con el código:

• en interfaz, documentar la interfaz
• en la aplicación, documentar los detalles de implementación

Java específica: cuando la documentación de la aplicación, utilizar {} @inheritDoc etiqueta "incluir" javadocs f rom de la interfaz.

Para más información:

• Official javadoc documentation
• Algunos no oficial advice.

Answer 2

Si utiliza el complemento GhostDoc, se actualiza la aplicación con el comentario de la interfaz al hacer clic derecho y seleccionar "Este documento" en el método.

Answer 3

Comentando la interfaz debe haber suficiente documentación para descubrir cómo usar la implementación real. La única vez que agregaría comentarios a la implementación es si tiene funciones privadas que se insertaron para satisfacer la interfaz, sin embargo, serían solo comentarios internos y no se verían en la documentación en línea ni a disposición de los clientes.

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

Answer 4

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

Answer 5

Para C# depende de la OMI: Si utiliza implementaciones de interfaz explícita, 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 estar documentados.

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 con el atajo Ctrl + Shift + D y es una de las teclas presionadas 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.

Answer 6

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

Aunque parece que @Nath puede sugerir una herramienta de documentación automatizada que ayuda a mantener las cosas juntas (suena genial si usa eso). Aquí en WhereIWorkAndYouDontCare los comentarios son para dev por lo que se prefiere

Answer 7

he creado una herramienta que post-procesa los archivos de documentación XML para añadir soporte para el < inheritdoc/> etiqueta.

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 a los que se hace referencia.

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