Código comentar: ¿Usted pone sus comentarios de código en interfaces o clases de hormigón, o ambos? [duplicar]

Question

    

Esta pregunta ya tiene una respuesta aquí:

    

        
•              Comentario la interfaz, la aplicación o ambos?                                      8 respuestas                          
    

    

¿Cuál es la mejor práctica en la documentación de las clases y las interfaces. Decir si tiene una clase concreta llamada Foo, que se deriva de una interfaz llamada IFoo. ¿Dónde poner sus comentarios para sus métodos? ¿Se duplica sus comentarios sobre la interfaz, así como la clase concreta?

Este es un ejemplo donde se duplican comentarios:

public class Foo : IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    public void DoSomething()
    {
    }
}

public interface IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    void DoSomething();
}

Answer 1

Me gustaría poner comentarios en ambos.

En las interfaces Me gustaría comentar la intención detrás de los elementos de interfaz y el uso.

En las implementaciones que comentaría las razones de la aplicación específica.

Answer 2

Me puse en general, ambos, sin embargo, que no dicen la misma cosa. El comentario de la interfaz debe describir el propósito resumen de este método / interfaz. Mientras que el comentario concreto hablará acerca de los detalles de implementación del método / clase en el contexto del propósito de la interfaz.

Answer 3

Los pongo en ambos, pero es un dolor que mantener en sincronía, en caso de duda yo sólo puse en la interfaz.

Lo hago porque me gusta la información sobre herramientas cuando se utiliza el código, que casi siempre se debe utilizar la interfaz ...

Answer 4

Su código de ejemplo no utiliza la implementación de interfaz explícita. El cliente de su código va a necesitar tanto desde s / él puede invocar el método ya sea a través de una clase u objeto de referencia de la interfaz. Con la implementación de interfaz explícita se puede omitir el comentario método de clase ya que el cliente no puede verlo. Esto es suponiendo que está utilizando la documentación XML para generar información de IntelliSense.

Answer 5

Los dos, pero me gustaría que fue construido en la funcionalidad para mantenerlos sincronizados

Answer 6

A <referTo>System. .... </referTo> etiqueta para enlazar los comentarios sería ideal

Answer 7

Realmente no usarlos en absoluto. En su lugar me aseguro de estructurar el código y el nombre de todos los métodos y variables de una manera que es obvio lo que hacen sin comentarios. El problema con los comentarios es que no compilan y no se ejecutan y no están probados por sus pruebas de unidad, por lo que su más o menos imposible mantenerlos en sincronía con el código.

Answer 8

Sólo para las interfaces. Debido a que en este caso no necesito a sincronizarlos. Mi IDE me ayuda a ver los comentarios de interfaz en clases concretas. Y generador de documentos API hace lo mismo.

Answer 9

Lo ideal sería que sólo la interfaz debe ser documentado, ya que define el contrato que cada aplicación concreta tiene que cumplir.