Crear un documento de estándares de codificación

Trabajo en una compañía de sistemas de control, donde el trabajo principal es SCADA y PLC , junto con otras cosas de sistemas de control.

El desarrollo de software no es realmente algo que la compañía hace, aparte de pequeños detalles aquí y allá, hasta que se tomó la decisión de crear un sistema interno de gestión y evaluación de proyectos.

Este proyecto ha sido asumido por personas que vinieron aquí como personas de software originalmente y en su mayoría somos junior.

El proyecto comenzó siendo pequeño, por lo que solo documentamos cosas como el diseño, las cosas de la base de datos, etc., pero nunca acordamos realmente un formato de codificación / convenciones.

Comenzamos a usar StyleCop para asegurarnos de que teníamos un código bien documentado, pero creo que necesitamos un documento oficial para codificar convenciones / prácticas para que podamos continuar con un buen estándar y si hay más trabajo de desarrollo importante en el futuro, cualquiera que trabaje en él Tiene una buena placa base.

Ahí está el problema, no tengo idea de cómo redactar un documento para codificar convenciones y estándares, todo en lo que puedo pensar es en ejemplos de buenas y malas prácticas (por ejemplo, casos de camellos al nombrar variables, evitar la notación húngara, etc.) estamos todos programadores suficientemente competentes (aparentemente) pero simplemente no tenemos una carta para este tipo de cosas.

Para aclararlo, mi pregunta es: ¿Cuáles son los aspectos y contenidos clave de un buen 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 respaldado por herramientas que permiten la verificación automática del código . Si sé que no puedo comprometerme a controlar la versión de ningún fragmento de código que no coincida con algunas reglas, me animaría a seguir esas reglas en mi código. Si, por otro lado, algún compañero programador ha escrito en algún lugar que necesito seguir una regla, no me importa una mierda esas reglas.

2. Estar bien pensado, en lugar de ser tu opinión personal . No dice simplemente: "a partir de ahora, 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 respondía: "bueno, me gustan las regiones, así que aún 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 constructivas, sugerencias y argumentos, lo que eventualmente hará que cambie su opinión original.

3. Estar 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 una diferencia de estilo, es decir, lo que los estándares quieren suprimir.

4. Estar generalizado, 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.

Como 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, simplemente cumpla con las pautas de Microsoft. Hay varios beneficios al hacerlo en lugar de crear sus propios estándares. Tomando los cuatro puntos anteriores:

1. No necesita reescribir las reglas de StyleCop para ajustarse 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.

2. Las pautas 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 comprende. Este fue exactamente mi caso; Cuando comencé el desarrollo de C #, encontré algunas reglas totalmente tontas. Ahora, estoy completamente de acuerdo con ellos, porque finalmente entendí por qué fueron escritos de esta manera.

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

4. Es posible que los nuevos desarrolladores que serán contratados en su empresa más adelante ya esté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 interno.

La primera cosa importante a tener en cuenta es que un documento de estándares de codificación no se trata de lo correcto y lo incorrecto. No se trata de lo bueno y lo malo o 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 presentado de la misma manera para que sea más fácil para un desarrollador cambiar el trabajo de una persona a otra sin el cambio de mentalidad necesario para leer el estilo de otra persona.

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

Con eso en mente, algunas cosas que debe aclarar en un documento de estándares de codificación son:

Convenciones de nombres

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

También algo más incluido en nuestros estándares fue una división de estándares para SQL, por lo que teníamos nombres similares para tablas, procedimientos, columnas, campos de identificación, disparadores, etc.

Sangría

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

Diseño

¿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 y registro de excepciones, es todo de cosecha propia o está utilizando una herramienta de terceros? ¿Cómo debe usarse?

Comentando

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

¿Qué tal el \\\ en Métodos para descripciones? ¿Son estos para ser utilizados? ¿Cuando?

Exposición

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

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

Apenas he arañado la superficie de lo que puede contener uno de estos documentos, pero KISS

No lo haga largo, aburrido e imposible de superar, o esas normas simplemente no se seguirán, manténgalo simple.

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

Por ejemplo, acabo de encontrar este: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

De todos modos, ten a mano tu lanzallamas.

Salud,

Odio la mayoría de los documentos estándar, ya que generalmente intentan sudar las cosas pequeñas e ignoran el panorama general.

Por ejemplo, casi todos dirán cómo nombrar variables o colocar corchetes. Este es un estilo puro y hace poco para ayudar realmente a un grupo de desarrolladores de código correctamente. Ignoran cosas como la estructura del directorio y el diseño del código. He visto documentos estándar que le dicen exactamente cuántos espacios colocar entre operadores y cuántas líneas en blanco colocar entre métodos. Todo esto generalmente termina con un montón de excepciones a la regla que solo muestra cuán inútiles son realmente, y luego son tan grandes que nadie puede seguirlos, lo que nuevamente hace una burla del punto que están tratando de hacer. .

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 en todo un proyecto, realmente no me importa cuál sea ese estilo. Entonces, mi primera regla para todos los documentos estándar es: mantener un estilo de codificación consistente dentro del proyecto . nadie debe dar un higo donde están los corchetes, siempre que sean todos iguales. Toma las guerras religiosas y empújalas :)

El segundo es el diseño del código. Cuando tomo una pieza de código, quiero ver que se presenta a lo largo de 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 a "cazar el código", lo cual es una molestia. Si se ve igual que el último proyecto en el que trabajé, puedo saber de inmediato dónde encontrar lo que estoy buscando y probablemente sea la mayor ayuda para trabajar con el código de otras personas que conozco. Por lo tanto, mantenga una estructura de cómo se presenta el código (por ejemplo, carpeta de documentación para documentos, interfaces para interfaces, etc., sea lo que sea que funcione para usted, pero sígalo).

Los artefactos de código también deben estar presentes, por lo que debe decir si el manejo de errores esperado es excepciones o códigos de error, es decir. documentar la funcionalidad arquitectónica que está en uso . También debería decir qué tipo de registro usar y cómo presentar 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 cómo cada lanzamiento de código tenía que tener su propio documento de operaciones diferente que les indicara a los operadores cómo saber si había salido mal. El registro de eventos, el archivo de registro (en cuyo caso), etc., son 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, o una base de datos personalizada, o parámetros de línea de comandos, o registro para otros).

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

Así que tome de eso los puntos principales: no intente hacer un documento legal , piense en cosas que no solo sean codificación, sino también cómo funciona el código y cómo el código se ajusta a las expectativas de otras personas. Luego confíe en las personas para que hagan un buen código y verá que lo hacen. (y si no lo hacen, puede tener palabras con ellos, no es necesario establecerlo como ley).

No lo hagas, 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 de su equipo. ¡Abrázala y ámalo! Lo guía continuamente, lo cual es mejor que cualquier documento que esté esperando a alguien a quien le moleste leerlo.