¿Debería escribir comentarios XML para interfaces, implementaciones concretas o ambas?

El título casi lo dice todo. ¿Dónde aplico mis comentarios XML? ¿Debería poner un comentario XML más genérico en la interfaz y uno más descriptivo en la clase de implementación? De esta manera:¿Debería escribir comentarios XML para interfaces, implementaciones concretas o ambas?

public interface IObjectRepository 
{ 
    /// <summary> 
    /// Returns an object from the respository that contains the specified ID. 
    /// </summary> 
    Object GetObject(int Id); 
} 

public ObjectRepository : IObjectRepository 
{ 
    /// <summary> 
    /// Retrieves an object from the database that contains the specified ID. 
    /// </summary> 
    public Object GetObject(int Id) 
    { 
     Object myData = // Get from DB code. 
     return myData; 
    } 
}

no he incluido <param> por razones de simplicidad.

¿Es una buena práctica para los comentarios o hay una manera diferente? ¿Acabo de omitir el comentario de la interfaz? Cualquier ayuda es apreciada.

Fuente

2011-04-05 Chev

posible duplicado de [? Comentario la interfaz, la aplicación o ambos] (http://stackoverflow.com/questions/759703/comment-the-interface-implementation-or-both) –

Posible duplicado de [Comentar la interfaz, la implementación o ambos?] (https://stackoverflow.com/questions/759703/comment-the-interface-implementation-or-both) – Olly

jaja esta pregunta ha estado aquí durante seis años. ¿Aburrido? – Chev

Puede definir el comentario en un archivo separado y luego usar la etiqueta <include> (see MSDN). De esta manera, puede escribir el comentario solo una vez, pero incluirlo como una documentación en varios lugares diferentes (por ejemplo, la declaración y la implementación de una interfaz).

Por supuesto, esto requiere un poco más de disciplina, porque es más difícil de escribir. También es un poco menos útil, porque no los verá en el código fuente. Sin embargo, si desea utilizar comentarios XML para compilar documentación, entonces es probable que sea un buen enfoque.

Fuente

2011-04-05 21:32:44

(No vi esto en la respuesta de "posible duplicado", así que lo estoy publicando aquí, porque es la respuesta específica de C#) –

No estaba al tanto de la etiqueta ''. Gracias. Si está bien comentar ambos, entonces creo que prefiero incluir comentarios más detallados sobre la clase de implementación y genéricos en la interfaz (como mi ejemplo en la pregunta). Realmente no lo veo como una repetición y como dijiste, es legible en la fuente. Sin embargo, me gusta mucho y probablemente lo encuentre útil en otros proyectos. – Chev

+1, pero como alguien a quien no le gustan los comentarios, esta parece ser una idea aún peor. Mi mayor problema con los comentarios es que pueden oscurecer la funcionalidad, especialmente al quedar desactualizados. Esto crea un nivel extra de abstracción que hace que sea más difícil mantenerlos actualizados. –

Prefiero hacer un comentario de las dos cosas. Recuerde que la definición del método de interfaz debe contener toda la información que el consumidor necesita para implementarla o llamarla. La implementación es relevante para los consumidores, así como para elegir cuál usar, por lo que también debería ser apropiado hacer comentarios.

La conclusión es errar por el lado de más claridad en lugar de menos.

Fuente

2011-04-05 21:40:03

Documente las interfaces.

Si la implementación es más general o más específica, p. puede trabajar con entradas o retornos más amplios o arroja resultados más específicos, luego documentar eso en la implementación.

Si la implementación no difiere de la interfaz, puede usar <inheritdoc />.

relacionadas: Inherit documentation in C#?

Fuente

2018-01-18 17:01:52

¿Debería escribir comentarios XML para interfaces, implementaciones concretas o ambas?

Respuesta

Cuestiones relacionadas