visual trucos studio .net stylecop xml-comments ghostdoc

.net - trucos - stylecop rules



¿En qué momento las configuraciones de Stylecop dejan de ser útiles y comienzan a ser molestas? (6)

Trabajo en un equipo en el que usamos un amplio conjunto de reglas en StyleCop y me pregunto cuáles son los pensamientos sobre el punto general en el que una herramienta de este tipo deja de ser útil y comienza a ser molesta. También utilizamos GhostDoc para que el código esté plagado de comentarios XML que hacen que el código sea mucho más difícil de leer y, por lo tanto, revisar. No tengo problemas con los comentarios XML y los encuentro muy útiles en lugares, ¿pero son realmente necesarios en todos los campos y propiedades?

Tenemos el admirable objetivo de "cada proyecto debe tener 0 Advertencias cuando se construye", pero seguramente este objetivo debe estar en contra de un conjunto de reglas de StyleCop razonable, de lo contrario se pierde un tiempo valioso para "arreglar" la causa de las advertencias de StyleCop.

¿Cuáles son los pensamientos sobre esto?

EDITAR Ahora me estoy preguntando cuál es el argumento para una herramienta como stylecop EN TODO? ¿Por qué no deshacerse de él y dejar que los estándares de codificación razonables y las buenas revisiones de código se encarguen del resto? Especialmente en un buen equipo competente? Seguramente entonces la tarea de obtener 0 Advertencias en realidad agregaría valor, ya que todas las Advertencias serían relevantes.

Creo que la única ventaja de GhostDoc es que le ahorra unos pocos segundos vitales al escribir un comentario XML desde cero. No creo que debas aceptar el comentario generado sin editarlo, lo que quizás sea contraproducente.

Aquí hay una combinación de una regla de Stylecop (SA1642: ConstructorSummaryDocumentationMustBeginWithStandardText) cumplida por el comentario xml generado por GhostDoc: ¿agrega algún valor al final del día?

/// <summary> /// Initializes a new instance of the <see cref="SomeCustomType"/> class. /// </summary> /// <param name="someParameter">The someParameter.</param> public SomeCustomType(string someParameter) { }

Cuando se necesita más tiempo para codificar alrededor de la regla, que lo que podría obtener al reducir el mantenimiento.

Como sabe, corregir un error lleva mucho más tiempo que escribirlo, por lo que aún puede hacer mucho trabajo adicional para que el código sea más robusto y mantenible antes de alcanzar el umbral.

Es útil tener un estilo de conjunto que todos usan, y para el nuevo código, StyleCop hará que esto sea un beneficio para todos.

Pero cuando agrega StyleCop a un proyecto existente que fue escrito con un estilo diferente , obtendrá cientos, o miles, o decenas de miles de violaciones de lo que son, esencialmente, reglas arbitrarias, tales como:

  • if debe ir seguido de un espacio
  • Los parámetros de la función deben aparecer todos en la misma línea o cada uno en una línea separada
  • Los comentarios de una sola línea deben comenzar con un espacio.
  • Los campos deben tener una línea en blanco entre
  • Una abrazadera de apertura no debe ir seguida de una línea en blanco
  • los nombres de los campos no deben comenzar con un guión bajo o ser prefijados
  • No se debe usar el parámetro predeterminado, use sobrecargas en su lugar
  • No prefieres llamadas locales con this
  • Orden de uso de declaraciones

Simplemente no tiene sentido editar miles de archivos existentes con cientos de miles de líneas de código para cumplir con tales reglas.

  • Con cualquier cambio, existe la posibilidad de que el cambio introduzca errores.
  • Si no está realizando cambios para corregir errores o introducir funciones, ¿por qué lo hace?

Si la respuesta es "callar a StyleCop", y ser honesto, hay más de una forma de hacerlo.

Su objetivo debe ser eliminar las advertencias que no representan errores, de modo que pueda ver, y luego corregir, las advertencias más problemáticas, que pueden hacer. La presencia de 1500 advertencias sobre el formato de los comentarios de una sola línea es un obstáculo que puede prescindir.

Por lo tanto, en una base de código heredada:

  • Edite el conjunto de reglas para deshabilitar cualquier regla estilística arbitraria con más de unas pocas violaciones. Estos son más problemas de lo que valen: no ocurrirá nada malo porque el proyecto usa guiones bajos para los campos, pero si accidentalmente causa un choque de nombres al intentar solucionarlo, es posible.
  • Donde haya una o dos violaciones, considere cuidadosamente si es mejor usar un archivo de supresión que editar el código de trabajo y probado para cerrar una advertencia estilística. No necesita colocar un conjunto de cambios con miles de cambios de espacios en blanco en cientos de archivos. Es fácil introducir una diferencia de comportamiento cuando crees que solo estás reformateando un bloque, y es fácil perderte algo así al revisar las líneas cambiadas.
  • Solo si está satisfecho de que la violación de la regla representa un error, debe cambiar el código. Entonces, ¿qué pasa si los parámetros no están en la misma línea? Reformatee el código, por supuesto, si necesita entenderlo ahora mismo y el formato lo dificulta. Pero no solo porque StyleCop lo dice.
  • Incluso agregar documentación de parámetros no es necesariamente inofensivo: si no conoce el código al revés, puede que simplemente esté creando sus propios conceptos erróneos para el próximo desarrollador.

Es de vital importancia que el código esté bien escrito y se pueda leer / mantener, pero utilizamos los ayudantes automáticos de formato de código de Visual Studio y Resharper para nuestro código, y AtomineerUtils para mantener los comentarios de la documentación XML en un formato estrictamente definido y ordenado.

Como resultado, las reglas principales de StyleCop son irrelevantes, ya que nuestro código siempre se adhiere a las reglas importantes "por defecto". Las reglas menores de StyleCop tienden a ser demasiado estrictas para el uso diario. (La mayoría de estas reglas solo hacen pequeñas mejoras, si las hay, en la calidad o la legibilidad del código, por lo que consideramos que el costo de adherirse a ellas es inaceptable. Permitimos a nuestros programadores un poco de "libertad de expresión", siempre que su código es fácil de leer por otros en el equipo, no nos importan las variaciones menores en el estilo de codificación). Entonces, después de evaluar StyleCop, no pude encontrar ningún beneficio en el mundo real.

En contraste, consideramos que FXCop es muy útil, ya que los problemas que resalta son más que solo problemas menores de legibilidad, ya que detectan errores graves y problemas de rendimiento de vez en cuando.

Esto es más una perorata que una pregunta, creo, pero estoy de acuerdo con usted en que:

  • Las reglas de estilo sobre-impuestas son algo malo.

Si bien obviamente debería haber pautas para el formato del código fuente, las reglas irrompibles sobre prescriptivas conducen a casos de esquina desagradables. Cumplir estrictamente con las reglas en todos los casos puede generar código excesivamente desordenado o sobrecargado.

La codificación es una variedad de escritura y, como tal, la Regla de Bonus de Orwell: "Rompe cualquiera de estas reglas antes de decir algo absolutamente bárbaro", también es necesario aplicar a las guías de estilo de codificación.

Soy escéptico de que la aplicación automática de estilos sea una buena idea, en un equipo de programadores competentes que pueden establecer y entender las guías de estilo. Las limas automatizadas son útiles para detectar errores accidentales, pero si se aplican con leyes altamente prescriptivas para el formato de código, no pueden tener en cuenta la regla de Orwell. Con un conjunto de reglas sólido, esto puede forzarle a escribir un código menos mantenible bajo la apariencia de mantenibilidad.

Si tiene programadores menos competentes en su equipo, cuya salida es un revoltijo a menos que sea forzado en el estilo, la aplicación podría ser una buena idea. (¡Pero entonces probablemente tengas problemas más grandes!)

  • Los comentarios automatizados son algo muy malo

No había visto GhostDoc antes, pero en realidad estoy un poco sorprendido.

El mismo ejemplo en su propia portada:

/// <summary> /// Determines the size of the page buffer. /// </summary> /// <param name="initialPageBufferSize"> /// Initial size of the page buffer. /// </param> /// <returns></returns> public int determineBufferSize(int initialPageBufferSize) {

es casi el ejemplo canónico de un comentario incorrecto, que agrega una visión absolutamente nula al código que documenta. Esto es absolutamente peor que ningún comentario-doc.

Todos los esquemas en la fuente-doc que siguieron a Javadoc son un poco sospechosos a veces, ya que saturan el código fuente con material que a menudo está dirigido a usuarios finales, una audiencia muy diferente a la de aquellos que leen el código. Pero esto es lo absoluto. No puedo imaginar quién pensó que esto era una buena idea.

Hay algunos puntos de su pregunta que atrajeron mi atención, por lo que me gustaría agregar algunas ideas a las respuestas anteriores.

No tengo problemas con los comentarios XML y los encuentro muy útiles en lugares, ¿pero son realmente necesarios en todos los campos y propiedades?

Algunos campos y propiedades son tan obvios para todos, que no necesitan una explicación. Por ejemplo, si una Coordinate clase tiene las propiedades X , Y y Z , no hay nada que explicar en los comentarios.

Pero cuando se trata de una herramienta como StyleCop, una herramienta no puede hacer una diferencia entre una propiedad obvia y una propiedad que tiene posibilidades de ser difíciles de entender cuando se descubre el código fuente por primera vez. Entonces, no, los comentarios no son necesarios en todas partes, pero o bien hacemos cumplir los comentarios en cada campo y propiedad, o deshabilitamos la regla y dejamos que el desarrollador decida.

Aquí hay una combinación de una regla de Stylecop (SA1642: ConstructorSummaryDocumentationMustBeginWithStandardText) cumplida por el comentario xml generado por GhostDoc: ¿agrega algún valor al final del día?

De algun modo. Algunas herramientas muestran constructores al igual que otros métodos, y no puede hacer ninguna diferencia visual entre los dos (a menos que tenga en cuenta el nombre de la clase). El comentario XML, por otro lado, es tan claro que hace que sea muy fácil entender que se trata de un constructor.

Por cierto, ¿qué más escribirías aquí?

  • ¿Algo más? No tener un estándar para los constructores dificultará la lectura del código y comprender que un método es un constructor en vistas donde ambos se muestran de la misma manera.

  • No hay ningún comentario en absoluto? Puede ser una solución, ya que tal comentario se puede generar fácilmente a partir del nombre de la clase. Pero hará las cosas más complicadas (¿por qué generar automáticamente un comentario en los constructores y no en otros métodos?). Además, si no proporciona una descripción para este constructor, ¿cómo puede alguien saber qué es un someParameter ?

Finalmente, para responder a su pregunta, nadie puede decir que cada regla de StyleCop siempre es útil en todos los casos. Pero recuerde que el disparate aquí es el objetivo de "cada proyecto debe tener 0 Advertencias cuando se construya", no el propio StyleCop . Si eres un desarrollador experimentado y escribes código limpio, no hay razón para no desactivar algunas reglas de StyleCop, al menos si entiendes bien qué significan, por qué están aquí y cuál será la consecuencia de no seguir la regla.

En nuestra empresa, tenemos una política de usar StyleCop para cada proyecto y si hay cientos de advertencias en un proyecto pequeño, hay un problema. Al mismo tiempo, a menudo tuve situaciones en las que deshabilité algunas reglas de StyleCop en clases enteras, simplemente porque perdería tiempo en hacerlas cumplir y no trae nada a nadie . Por otra parte, no aprecié nada cuando mi colega deshabilitó FxCop / StyleCop solo para poder escribir nombres de clases, métodos y propiedades en francés (estoy en una empresa francesa que también trabaja con desarrolladores de habla inglesa ), entonces diría que para algunas personas, ambas herramientas deben estar habilitadas cada vez, sin capacidad para deshabilitarlas.

StyleCop es una herramienta . No se supone que debe ser perfecto y no debe satisfacer las necesidades de todos.

Personalmente digo "Sí, es importante", porque cuando está ejecutando un equipo de desarrolladores, StyleCop lo ayuda a garantizar que se cumplan sus directrices de codificación. Ese es exactamente su propósito: evaluar los estándares de codificación de manera automatizada, mensurable y consistente. Si no quieres la capacidad de hacer eso en tu proceso de construcción, entonces tienes razón, es una pérdida de tiempo.

Usted mismo lo dice: el objetivo de advertencia de cero "debe estar en contra de un conjunto de reglas de StyleCop razonable". No tiene sentido ejecutar una herramienta con una configuración que no coincida con sus necesidades. Si una regla es "molesta" para usted, entonces apáguela, pero para alguien más puede ser de vital importancia.

En cuanto a su pregunta "si bien agrega valor": sí. La gente subestima el valor de la consistencia. Si todos sus constructores tienen el mismo estilo de comentario, si todos los Intellisense para propiedades en su proyecto tienen la misma estructura, es un obstáculo menos mental (no importa cuán pequeño) lidiar con ellos. Y con las herramientas que lo automatizan, es casi cero esfuerzo. ¿De qué quejarme?