1. Inicio
  2. Pregunta y respuesta
  3. El campo debe tener un encabezado de documentación - Estilo Cop - ¿Código olor?

El campo debe tener un encabezado de documentación - Estilo Cop - ¿Código olor?

2009-07-07 8 views
16

Yo estaba corriendo poli estilo contra algunos de mi código y dieron unos cuantos:El campo debe tener un encabezado de documentación - Estilo Cop - ¿Código olor?

SA1600: The field must have a documentation header.

Ahora no me malinterpreten me gusta poli estilo, es muy bueno cuando se trabaja en un proyecto con más de una persona pero esta regla me parece un poco excesiva. ¿Por qué querría agregar:

/// <summary> 
    /// blah blah blah 
    /// </summary>

a la parte superior de cada variable. Estoy bastante seguro de que recuerdo a alguien diciendo (Martin Fowler, Kent Beck ... realmente no recuerdo ATM) que el comentario debería decir "por qué" no "qué" y realmente no puedo ver cómo puedes explicar por qué en un variable.

También encuentro el código que tiene comentarios en cada variable más difícil de leer porque todo lo que ves es pelusa.

Pienso que si tiene que explicar qué es cada variable, está fallando en términos de nombres.

¿Alguien más encuentra las variables de comentario un poco olor a código o solo soy yo?

Fuente

2009-07-07 Nathan W

+0

Bob Martin dice * "Los comentarios son ** siempre ** fallos" * (énfasis añadido) -CC, Cap 4, p. 54. Por lo tanto, dado que esta regla de StyleCop exige comentarios en todos estos lugares todo el tiempo (suponiendo que trabajas todas tus advertencias, y debes hacerlo porque están ahí para ayudarte a escribir un buen código), esta regla no es válida según el tío Bob. Si se necesita un comentario, que es un mal necesario en la rara ocasión, usted, como desarrollador, lo sabrá, por lo que lo agregará. En ese caso, las reglas sobre el formato xml son buenas, así que guardé todas las reglas excepto 1600-02, 1611, 1615, 1618 para aliviar algunos problemas que menciona. – toddmo

Respuesta

12

No diría que comentar una variable es siempre un olor a código (y tampoco parece que sea eso lo que dices). Estoy de acuerdo en que al comentar cada variable, cada vez es, al menos, excesivo, y posiblemente indicativo de una mala denominación. De hecho, algunos argumentarían que cualquier comentario de es un olor a código, y que los nombres descriptivos y las rutinas cortas son más legibles y previenen la situación donde se ha cambiado el código, pero los comentarios no se han actualizado (lo cual ciertamente me ha mordido en algunas bases de código heredado). No creo que llegue tan lejos, pero si puede escribir un código que se explica por sí mismo sin una explicación adicional, parece preferible.

Así que sí, básicamente lo que dices.

Fuente

2009-07-07 23:58:12

+0

Robert C. Martin trata estos problemas en el código de limpieza de su libro. Él tiene una visión interesante de las cosas. –

+0

Lo que piensas que es un autocomentario es muy diferente a lo que yo, el chico que entra y leo tu código dentro de seis meses, consideraré autocomplacerme. Y si el comentario no coincide con el código, corrige el comentario. –

0

Creo que la respuesta correcta aquí es "depende". Sin duda, puede explicar el "por qué" de una variable que se marca static/const, o business logic/restrictions en los contenidos de la variable. Habiendo dicho eso, estoy de acuerdo en que ver todos los comentarios variables impide la legibilidad y puede indicar a ciegas después de un nomenclatura estándar o incorrecta.

Fuente

2009-07-07 23:57:03

6

XML Los comentarios son ligeramente diferentes a otros comentarios.

Si configura las cosas correctamente, puede hacer que aparezcan en consejos de herramientas en Visual Studio Y usarlas para crear documentación de estilo de MSDN con Sand Castle. Creo que deberían decirte lo que está haciendo la cosa cuando no tienes acceso al código fuente.

El punto es que estos comentarios pueden aparecer sin el código fuente que están comentando. Deberían ser útiles para otro devloper que no puede ver su código y no le importa cómo está haciendo las cosas.

No conozco la herramienta "Cop" que está utilizando, pero sería bueno tener una forma de señalizar la herramienta que tiene la intención de dejar un parámetro en blanco. Por lo tanto:

/// <param name="fubar"></param> // Haven't gotten around to it 
    /// <param name="portNumber" /> // I intend this parameter to have no help

He trabajado en proyectos en los que tenemos que llenar todo y nos obtener cosas como:

/// <param name="portNumber">The Port Number</param> // What else could it be?

Si no desea utilizar las características descritas anteriormente, seguir adelante apague la regla de Cop de estilo.

Fuente

2009-07-07 23:59:17 jrcs3

+2

Sí, uso XML mucho en los métodos públicos, pero comentar variables privadas con comentarios XML me parece un desorden innecesario. –

2

Totalmente de acuerdo y lo primero que desactivé en StyleCop. Si necesita explicarlo, lo ha nombrado de una manera que necesita explicación y ha fallado al hacer el código self documenting.

Fuente

2009-07-11 07:31:42

1

Debe intentar GhosDoc es una manera fácil de tener documentación automatizada para cada miembro del código en su aplicación. Simplemente instálalo, haz clic con el botón derecho sobre el miembro y selecciona document this!

Fuente

2010-01-25 01:47:49

+1

Por definición, GhosDoc solo puede agregar 'documentación' que ya puede derivarse del código (es decir, del tipo de variable y el nombre). Por lo tanto, genera _useless_ documentation (casi por definición); no te dice nada que no puedas determinar a partir del código. Solo está agregando ruido redundante. – andrewf

18

Esta es una publicación bastante antigua, pero me encontré con ella mientras buscaba una solución para este problema, por lo que ofrecería una solución.

Si abre el archivo de Settings.StyleCop en el editor de reglas, seleccionar las reglas de documentación nodo, a continuación, en los ajustes detallados sección a la derecha anular la selección de la incluir campos opción. Ahora ya no se le pedirá que documente los campos.

Fuente

2011-07-20 07:52:13 Nixus

+2

Buena llamada, pero debe tenerse en cuenta que esto solo funciona para los campos y no resuelve el problema de las propiedades. – JasCav

+0

Sí, ¿por qué no simplemente hacer clic en todos los elementos con los que no está de acuerdo hasta que StyleCop sea compatible con el código que escribe? Ese sería el camino más fácil de todos. –

Cuestiones relacionadas

 Cuestiones relacionadas