Creando un documento de estándares de codificación

¿Cuáles son los aspectos y contenidos clave de un buen documento de estándares de codificación?

1. Ser compatible con herramientas que permiten la comprobación automática del código . Si sé que no puedo comprometerme a controlar cualquier versión de código que no coincida con algunas reglas, me recomendarían seguir esas reglas en mi código. Si, por otro lado, algún programador compañero ha escrito en algún lugar que debo seguir una regla, no me importan las reglas.

2. Ser bien pensado, en lugar de ser tu opinión personal . No dices claramente: "de ahora en adelante, ya no usamos regiones, porque no me gustan las regiones". Más bien, explicaría que las regiones fomentan el crecimiento del código y no resuelven ningún problema importante .

   La razón es que en el primer caso, su colega contestaría: "bueno, me gustan las regiones, por lo que todavía las usaría". En el segundo caso, por otro lado, obligaría a las personas que no están de acuerdo a venir con críticas, sugerencias y argumentos constructivos, lo que eventualmente hará que cambie su opinión original.

3. Estando bien documentado . La falta de documentación crea confusión y espacio para la interpretación ; La confusión y la posibilidad de interpretación conducen a la diferencia de estilo, es decir, lo que los estándares quieren suprimir.

4. Estar extendido, incluso fuera de su empresa . Un "estándar" utilizado por veinte programadores es menos estándar que un estándar conocido por cientos de miles de desarrolladores en todo el mundo.

Ya que estás hablando de StyleCop, supongo que la aplicación está escrita en uno de los lenguajes de .NET Framework.

En ese caso, a menos que tenga razones serias para hacerlo de manera diferente, solo siga las pautas de Microsoft. Hay varios beneficios en hacerlo en lugar de crear sus propios estándares. Tomando los cuatro puntos anteriores:

1. No es necesario volver a escribir las reglas de StyleCop para que se ajusten a sus propios estándares. No digo que sea difícil escribir tus propias reglas, pero si puedes evitar hacerlo, significa que tienes más tiempo para hacer algo útil en su lugar.

2. Las directrices de Microsoft están muy bien pensadas. Hay posibilidades de que si no está de acuerdo con algunos de ellos, podría ser porque no los entiende. Este fue exactamente mi caso; cuando comencé a desarrollar C #, encontré algunas reglas totalmente tontas. Ahora estoy completamente de acuerdo con ellos, porque finalmente entendí por qué se escribieron de esta manera.

3. Las directrices de Microsoft están bien documentadas, por lo que no tiene que escribir su propia documentación.

4. Los nuevos desarrolladores que serán contratados en su empresa más adelante ya estarán familiarizados con los estándares de codificación de Microsof. Hay algunas posibilidades de que nadie esté familiarizado con su estilo de codificación interna.

Lo primero que se debe tener en cuenta es que un documento de estándares de codificación no trata sobre lo correcto o lo incorrecto. No se trata de lo bueno y lo malo o de qué método es mejor.

El propósito de un documento de estándares de codificación es asegurarse de que todo el código esté diseñado, escrito y dispuesto para que sea más fácil para un desarrollador cambiar de una persona a otra sin el necesario cambio de mentalidad para leer el estilo de otra persona .

Se trata de uniformidad, y nada acerca de "lo correcto y lo incorrecto"

Teniendo esto en cuenta, algunas cosas que debe aclarar en un documento de estándares de codificación son:

Convenciones de nomenclatura

¿Cómo nombrarás tus métodos, variables, clases e interfaces? ¿Qué notación usarás?

También se incluyó en nuestros estándares una división de estándares para SQL, por lo que tuvimos nombres similares para tablas, procedimientos, columnas, campos de identificación, activadores, etc.

Indentación

¿Qué vas a usar para la sangría? ¿Una sola pestaña? 3 espacios?

Layout

¿Se mantendrán las llaves en la misma línea que la línea del método de apertura? (generalmente java) o en la siguiente línea o una línea propia? (generalmente C #)

Manejo / registro de excepciones

¿Cuáles son sus estándares para el manejo de excepciones & el registro, ¿se trata de una herramienta de terceros? ¿Cómo se debe utilizar?

Comentarios

Tenemos estándares para dictar la corrección gramatical, y los comentarios comienzan en la línea antes o después, no en la misma línea, esto aumenta la legibilidad. ¿Los comentarios tendrán que ser sangrados a la misma profundidad que el código? ¿Aceptarás los bordes de comentario utilizados en textos más grandes?

¿Qué hay de los \\\ en Métodos para las descripciones? ¿Son para ser utilizados? Cuando?

Exposure

¿Deberían todos sus métodos y campos implementar el nivel de acceso más bajo posible?

También es importante tener en cuenta. Un buen documento de estándares puede hacer mucho para ayudar a revisar el código, ¿cumple con estos estándares mínimos?

Apenas he arañado la superficie de lo que puede aparecer en uno de estos documentos, pero K.I.S.S.

No lo haga largo, aburrido e imposible de superar, o no se seguirán esos estándares, manténgalo simple.

Estaba pasando por este proceso varias veces. Y el enfoque más exitoso (aunque con baches de todos modos) fue tomar el documento "Estándares de codificación" de una compañía bien conocida y modificarlo para que se ajuste a sus necesidades.

Por ejemplo, encontré este: enlace

De todos modos, mantenga su lanzallamas a mano.

Saludos,

Odio la mayoría de los documentos de estándares, ya que generalmente tratan de sudar las cosas pequeñas e ignoran la imagen más grande.

Por ejemplo, casi todos dirán cómo nombrar variables o colocar paréntesis. Este es un estilo puro y hace poco para ayudar realmente a un grupo de código de desarrollo correctamente. Ignoran cosas como la estructura de directorios y el diseño del código. He visto documentos de estándares que le indicaron exactamente cuántos espacios colocar entre operadores y cuántas líneas en blanco colocar entre métodos. Todos estos generalmente terminan con una tonelada de excepciones a la regla que solo demuestra lo inútiles que son, y luego son tan grandes que nadie puede seguirlas, lo que, de nuevo, se burla del punto que intentan explicar. .

Ahora, para mí, utilizo muchos bits diferentes de software de muchas personas diferentes y todos tienen estilos diferentes. Simplemente me acostumbro a esto, no me quejo de que no haya un estilo común en todos los grupos de desarrollo. Mientras el código sea un estilo común a lo largo de un proyecto, realmente no me importa cuál es ese estilo. Así que mi primera regla para todos los documentos de normas es: Mantener un estilo de codificación consistente dentro del proyecto . nadie debe dar un higo donde están los corchetes, siempre y cuando todos sean iguales. Toma las guerras religiosas y empújalos :)

El segundo es el diseño de código. Cuando recojo una pieza de código, quiero ver que se presenta en líneas similares a otras piezas de trabajo similares. Si tengo un servicio web, quiero que el nombre del contrato wsdl sea claro, quiero que el nombre de la implementación sea claro. No quiero que alguien presente un diseño nuevo y diferente para archivos y clases. Eso significa que tengo que jugar "cazar el código", que es una molestia. Si se ve igual que el último proyecto en el que trabajé, puedo saber de inmediato dónde puedo encontrar lo que estoy buscando y es probablemente la mayor ayuda para trabajar con el código de otras personas que conozco. Por lo tanto, mantenga una estructura de cómo se distribuye el código (por ejemplo, la carpeta de documentación para documentos, interfaces para interfaces, etc., sea lo que sea más conveniente para usted, pero cúmplalo).

Los artefactos de código también deben estar presentes, por lo que debe indicar si el manejo de errores esperado son excepciones o códigos de error, es decir, la funcionalidad de arquitectura de documento que está en uso . También debe indicar qué tipo de registro se debe usar y cómo presentar los registros / manejo de errores al usuario o cualquier subsistema que se use para administrar el código en la naturaleza. Trabajé en un lugar donde cada proyecto se registraba de manera diferente; era patético que cada lanzamiento de código tuviera que tener su propio documento de operaciones diferente que les decía a los operadores de operaciones cómo saber si había salido mal. El registro de eventos, el archivo de registro (en cuyo caso, dónde), etc., son todos válidos aquí. Lo mismo se aplica a otros aspectos comunes del código: cómo configurarlo (no tiene sentido usar un archivo .config para algunos programas, una base de datos personalizada, parámetros de línea de comandos o registro para otros).

En resumen, lo único que importa es consistencia . Y como los documentos de estándares enormes son demasiado para leer y memorizar, prefiero simplemente informar a las personas de las cosas que no pueden ver (por ejemplo, los estándares de arquitectura como el registro) y decirles que mantengan el código que escriben de manera coherente con lo que hay actualmente. ¡Y si aún no tiene un código, no necesita un documento de estándares! (bueno, no hasta que hayas escrito lo suficiente como para que sea útil).

De modo que, a partir de eso, saque los puntos principales: no intente hacer un documento legal , piense en cosas que no son solo codificación, sino también cómo funciona el código y cómo encaja con otros. expectativas de la gente Luego confíe en la gente para hacer un buen código y verá que lo hacen. (y si no lo hacen, puede tener palabras con ellos, no es necesario que lo establezca como ley).

No, es una pérdida total de tiempo y energía. StyleCop es excelente y fue establecido durante años por personas mucho más experimentadas y mucho más inteligentes que usted o cualquiera en su equipo. ¡Abrázalo y ámalo! Lo guía continuamente, lo cual es mejor que cualquier documento que espere a que alguien se moleste en leerlo.