¿Cómo deberían ser diferentes los comentarios para la interfaz y los métodos de clase?

Question

Me encontré con este dilema cuando trabajaba en una aplicación web ASP.net utilizando Web Client Software Factory (WCSF) en C#, y lo mismo podría aplicarse a otra plataforma e idiomas. Mi situación es la siguiente:

estoy definiendo un I Ver interfaz para cada control de la página web/usuario en función de paradigma WCSF, a continuación, tienen la clase de página implementar el I interfaz de Vista, básicamente, la implementación de cada uno de los métodos definidos en La interfaz. Cuando traté de agregar xml-documentation en el nivel de método, básicamente me encontré repitiendo el mismo contenido de comentario para ambos métodos de interfaz y su contraparte en la clase de implementación.

Así que mi pregunta es: ¿debería haber alguna diferencia sustancial entre el contenido de la documentación en el método de la interfaz y el método de clase correspondiente? ¿Deberían estar enfatizando en un aspecto diferente o algo así?

Alguien me dijo que el comentario del método de interfaz debería decir "qué" se supone que debe hacer el método, y el comentario del método de clase debería decir "cómo" lo hace. Pero recuerdo haber leído antes que el comentario del nivel de método solo debería decir "qué" se supone que debe hacer el método, nunca el detalle de implementación del método, ya que la implementación no debería ser una preocupación para los usuarios del método y podría cambiar.

Answer 1

Personalmente, creo que estos comentarios deberían ser los mismos: ambos deberían decir "lo que el método va a hacer", en sus términos.

No hay ninguna razón para que los comentarios XML mencionen los detalles de implementación. La única excepción, potencialmente, sería mencionar los posibles efectos secundarios (es decir: este método puede llevar mucho tiempo), pero yo personalmente lo haría en la sección <remarks> de los comentarios del documento XML.

Answer 2

Llámame un loco, pero usaría un nombre descriptivo para el método y lo llamaría un día (no hay comentarios para ninguno de los dos). Podría agregar comentarios a la implementación si algo es sorprendente o por qué no es obvio.