¿Qué debería estar en un estándar de codificación? [cerrado]

¿Qué debería estar en un buen estándar de codificación (léase: útil)?

• Cosas que el código debería tener.
• Cosas que el código no debería tener.
• ¿El estándar de codificación debe incluir definiciones de cosas que el lenguaje, el compilador o el formateador de código impone?
• ¿Qué pasa con métricas como la complejidad ciclomática, líneas por archivo, etc.?

Una razón para cada requerimiento. De esta manera, seguir el estándar no se convierte en una especie de culto a la carga y la gente sabe que está bien cambiar el estándar si el motivo ya no se aplica, o violar el estándar en casos específicos donde el motivo claramente no se aplica. .

Tabs vs Spaces! Recibo actualizaciones locas cuando uno de mis colegas accidentalmente ingresa muchas pestañas para que los espacios cambien al repositorio

Convenciones de nombres

EDITAR: Con esto me refiero a las pautas de nomenclatura, no a las reglas de nomenclatura.

Por ejemplo, una directriz sería All boolean values should begin with Is/Can/Has/etc when possible. Una regla seríaAll boolean values must start with Is

Un estándar de codificación para un grupo debe incluir las opciones del compilador para advertencias y errores que deben abordarse.

Los programadores deben tener la libertad de aumentar las advertencias para su propio código, pero debe haber una línea de base para que leer y trabajar con el código de otra persona no desordene la salida que obtiene del compilador.

Tal estándar también debería abordar cómo los programadores pueden deshabilitar tales advertencias caso por caso, en caso de que haya un código excepcional que de otra manera no se conformaría.

Algunos estándares que me gustan (sé que hay muchos de ellos, pero esos son los que prefiero):

• 80% de cobertura de pruebas unitarias
• Propiedad colectiva del código (escriba el código para que lo lean sus compañeros de equipo, no el compilador)
• Escribir comentarios Escribe lo que le dirías a un recién llegado.
• Mantenlo simple

Los estándares de codificación ayudan un poco cuando está escribiendo el código la primera vez, ayudan mucho cuando usted, o su reemplazo, tiene que actualizar el código 2 años después.

El estándar ideal conduce al código donde puede saltar a cualquier página arbitraria en el código y comprender exactamente lo que está haciendo en la primera lectura, porque

• los nombres describen claramente qué datos se están manipulando,
• las llaves dejan claro el flujo de control,
• los comentarios explican cualquier algoritmo no obvio, etc.

Por otro lado, demasiados estándares arbitrarios pueden interrumpir el flujo de escritura de código. Por lo tanto, creo que cada elemento de una convención de codificación propuesta debe evaluarse con respecto a estos 2 criterios:

• ¿Esta regla ayuda a garantizar que el código sea correcto ?
• ¿Esta regla ayuda a garantizar que el código sea claro ?

Si ninguno de los dos es cierto, el elemento es arbitrario y probablemente innecesario.

Incluiría las siguientes cosas en un estándar que escribo:

Para mayor claridad:

• Organización de archivos: al especificar un orden fijo para los elementos en un archivo, el equipo puede navegar fácilmente por otros archivos. No debería tener que buscar para encontrar #defines o definiciones de estructura.

• Convenciones de nomenclatura: la nomenclatura constante ayuda a la legibilidad. Pero evite especificar demasiadas reglas, lo que perjudica la capacidad de escritura.

• Estructura del Código Colocación de llaves, niveles de sangría, espacios frente a pestañas, etc. Sí, esta puede ser una preferencia personal fuerte, pero el objetivo es un código claro. Encuentre la mejor opción para el equipo y manténgala.

Para la corrección:

• Mejores prácticas específicas para su tipo de problema: Reglas sobre asignación de memoria, concurrencia o portabilidad.

• "Const Correctness", uso apropiado de staticy volatile, etc.

• Reglas sobre macros de preprocesador y otras características del lenguaje fácilmente abusables.

Ideas inspiradoras y pragmáticas que hacen pensar a las personas, en lugar de restricciones negativas que impiden que las personas piensen.

De lo contrario, obtienes monos de código que temen ir tras los plátanos .

¿Qué debería estar en un estándar de codificación? Tan poco como sea posible. Menos bastante más. Y con justificación, por favor.

No porque sea un codificador de vaqueros que no quiere ningún proceso, sino porque he visto especificaciones de codificación pesadas sin lógica detrás de eso (presumiblemente) "Encontré esto en la 'Red en algún lugar en el '95" que acaba convirtiéndose en una pesadilla burocrática para trabajar.

Algunas personas honestamente parecen creer que al aumentar los estándares verán un aumento correspondiente en la "calidad" del código y tal vez por esa medida lo harán. Mientras tanto, ignorarán la arquitectura, el rendimiento, el sentido común y muchas otras cosas que terminan importando más que la cantidad de líneas en un archivo.

Un procedimiento para revisiones de código para hacer cumplir el estándar. Ah, y para encontrar errores también.

Algún buen sentido común no iría mal; hay demasiados documentos estándar de codificación que funcionan en puntos irrelevantes (elementos como el tipo de fuente y el tamaño son uno de los más extremos que he visto).

Lo mejor que puedes hacer si estás en un grupo de desarrolladores es hablar entre ellos y mirar tu código, formar un consenso sobre lo que es aceptable y si necesitas escribir los puntos principales como pautas, pero mantenerlos como solo esas pautas. Si no puede justificar cualquier divergencia de las pautas, realmente debería considerar por qué lo está haciendo.

Al final del día, el código claro y comprensible es más importante que cualquier regla rígida sobre diseño o tipografía.

Como otros han mencionado, la cobertura de prueba de código es importante. También me gusta ver:

• Estructura del proyecto. ¿Las pruebas son parte del código o están en un directorio proyecto / paquete / separado? ¿El código de la interfaz de usuario vive con el material de fondo? Si no, ¿cómo se divide en compartimentos?

• Proceso de desarrollo. Escribir pruebas antes del código? ¿Arreglar construcciones rotas tiene prioridad sobre el desarrollo? ¿Cuándo se realizan las revisiones de código y qué deben cubrir?

• Gestión del código fuente. ¿Qué se registra cuando? ¿Los documentos de diseño y los planes de prueba están controlados por revisión? ¿Cuándo se ramifican y cuándo etiquetan? ¿Mantiene las compilaciones anteriores, y si es así, cuántas / por cuánto tiempo?

• Estándares de implementación. ¿Cómo se empaqueta una compilación? ¿Qué necesita ir en las notas de la versión? ¿Cómo se crean / controlan / ejecutan los scripts de actualización?

Olvídese de toda esa basura sobre las convenciones de nomenclatura, el formato y cuántas líneas puede haber en una función / método / módulo. Una regla: use el estilo existente en lo que sea que esté editando. Si no le gusta el estilo de alguien, selecciónelo en una revisión de código. La única excepción podría ser la cuestión de las pestañas contra espacios, aunque solo sea porque muchos editores / IDEs convertirán ciegamente uno a otro, y luego terminarás destruyendo tu historial de cambios porque cada línea se cambió.

Creo que en realidad hay dos cosas que abordar, y de hecho las consideraría por separado porque no pueden abordarse de la misma manera, aunque considero que ambas son importantes.

• El aspecto técnico: que tiene como objetivo evitar el código arriesgado o mal formado (incluso si es aceptado por el compilador / intérprete)
• El aspecto de la presentación: que se refiere a hacer que el programa sea claro para los lectores

El aspecto técnico que califico de Coding Standard , al igual que Herb Sutter y Andrei Alexandrescu con sus estándares de codificación C ++ . La presentación califico de Estilo de codificación , que incluye la convención de nomenclatura, sangría, etc.

Norma de codificación

Debido a que es puramente técnico, un estándar de codificación puede ser principalmente objetivo. Como tal, cada regla debe estar respaldada por una razón. En el libro al que me referí cada elemento tiene:

• Un título, simple y al grano.
• Un resumen, que explica el título.
• Una discusión, que ilustra la cuestión de hacer lo contrario y, por lo tanto, expone la justificación
• opcional Algunos ejemplos, porque un buen ejemplo vale más que mil palabras
• opcional Una lista de excepciones para las cuales no se puede aplicar esta regla, a veces con soluciones alternativas
• Una lista de referencias (otros libros, sitios web) que han discutido este punto

La justificación y las excepciones son muy importantes, ya que resumen el por qué y cuándo.

El título debe ser lo suficientemente explícito como para que durante las revisiones uno solo necesite tener una lista de títulos (hoja de trucos) para trabajar. Y obviamente, agrupe los artículos por categoría para que sea más fácil buscar uno.

Sutter y Alexandrescu lograron tener una lista de solo cien artículos, a pesar de que C ++ se considera peludo;)

Estilo de codificación

Esta parte es generalmente menos objetiva (y puede ser francamente subjetiva). La intención aquí es garantizar la coherencia, porque esto ayuda a los mantenedores y los recién llegados.

No desea entrar en una guerra santa sobre qué estilo de sangrado o llave es mejor aquí, hay foros para esto: por lo tanto, en esta categoría, usted hace las cosas por consenso> voto mayoritario> decisión arbitraria de los líderes.

Para ver un ejemplo de formato, consulte la lista de opciones de Estilo artístico . Idealmente, las reglas deben ser lo suficientemente claras y completas como para que un programa pueda reescribir el código (aunque es poco probable que alguna vez codifique uno;))

Para la convención de nomenclatura, trataría de distinguir fácilmente las clases / tipos de las variables / atributos.

También es en esta categoría que clasifico las "medidas" como:

• prefieren métodos cortos a largos: generalmente es difícil acordar cuánto dura
• prefiera regresar temprano / continuar / descanso para reducir la sangría

Misceláneo

Y como última palabra, hay un elemento que rara vez, si alguna vez, se discute en los Estándares de Codificación, tal vez porque es particular de cada aplicación: la organización del código. El problema arquitectónico es quizás el problema más sobresaliente, arruine el diseño inicial y se verá afectado por años dentro de este momento. Tal vez debería agregar una sección para el manejo básico de archivos: encabezados públicos / privados, gestión de dependencias, separación de preocupaciones, interacción con otros sistemas o bibliotecas ...

Pero esos son nada si no se aplican realmente y hacen cumplir .

Cualquier violación debe ser mencionada durante las revisiones de código, y ninguna revisión de código debe estar bien si hay una violación pendiente:

• arreglar el código para que coincida con la regla
• arregla la regla para que el código ya no se destaque

Obviamente, cambiar una regla significa obtener el "avance" de los líderes.

Me gusta el formato en las Pautas de diseño del marco , incluye una sección general y los fundamentos de las pautas. El bit más útil son los detalles que comienzan con Do, Do Not, evitar y considerar.

Aquí hay un ejemplo en la sección Implementación de miembros de la interfaz Explícitamente tiene los siguientes elementos (tenga en cuenta que eliminé los fundamentos por el bien de bervity)

Evite implementar miembros de interfaz explícitamente sin tener una razón sólida para hacerlo.

Considere implementar miembros de la interfaz explícitamente si los miembros están destinados a ser llamados solo a través de la interfaz.

No utilice miembros explícitos como límite de seguridad.

No proporcionar un miembro virtual protegida que ofrece la misma funcionalidad que la> miembro implementado de forma explícita si la funcionalidad está destinado a ser especializados por las clases derivadas.

Esto crea un buen tono general. Al usar Evitar y considerar puede permitir que los desarrolladores utilicen su criterio. También porque son pautas y no reglas, los desarrolladores pueden encontrarlos más sabrosos y, a su vez, más propensos a seguirlos.

Parece que nadie mencionó la seguridad: en un estándar de codificación debe tener referencia a los requisitos de código seguro (por ejemplo, el uso de módulos de validación de entrada, no permitir funciones débiles conocidas como strcpy, requisitos de manejo de errores, etc.)

Ejemplos. Ejemplos ordenados, no triviales, cercanos al mundo real que hacen uso de todas las reglas. Comentarios (no necesariamente parte del código) qué parte del ejemplo sigue a qué regla.

Plantillas. No del tipo C ++, sino algo para copiar, pegar y rellenar en vivo. Es mucho más fácil obtener ese comentario repetitivo de 24 líneas justo cuando tiene una referencia para copiar.

Característica número uno: un máximo absoluto de dos páginas.

Esto es algo que desea que cada desarrollador lea y recuerde. No debería tener que buscar en el estándar cada vez que necesite escribir una nueva función (o peor aún, una nueva línea). Por lo tanto, manténgalo breve y mantenga solo las reglas que realmente brinden un mayor valor al producto final.

Los estándares de codificación son realmente varios elementos:

Convenciones de codificación

• estas cosas no necesitan una razón distinta a la "consistencia de la base del código" por ej. usar '_' en variables miembro privadas o no.
• Podría haber varios enfoques correctos. Solo necesito elegir uno por consistencia. por ej. manejo de errores utilizando excepciones o códigos de error.

Mejores prácticas

• estos artículos siempre necesitan una buena razón con algunos ejemplos claros

por ej. Nunca deje el Catch vacío después de intentarlo.

try { Foo(); } catch { //do nothing }

1) Si hay una excepción lanzada por Foo () puede causar otros problemas en las funciones que siguen, que se supone que foo tuvo éxito.

2) El controlador de errores global no notificará al equipo de soporte de la excepción cuando ocurra en prod

• cubre las prácticas de "Codificación defensiva", como usar Asserts para probar sus suposiciones.

Entorno de codificación

• herramientas que usa todo el equipo. por ej. VS 2010, Resharper, Horno, etc.

Las normas de codificación, cuando están escritas en papel, son muy efectivas. Me gusta cómo Go publica su estándar de codificación. Tiene la herramienta gofmtpara formatear el texto del programa a un formato. Cualquier debate sobre el formato de codificación simplemente resultará como un parche para las fuentes de gofmt.

En cuanto a lo que debe tener el formato,

• Cómo nombrar variables, macros, constantes, literales, funciones, etc.
• cómo colocar {,}, (,), [,] cuando se trata de if, cuerpo de la función, bloques de instrucciones para cualquier otro propósito,
• qué tan anchas deben ser las hendiduras,
• cuántos caracteres se permite una línea de texto
• cuántos niveles de sangría están permitidos antes de que el código sea rechazado / enviado para refactorizar
• cuántas líneas de código se permiten por función antes de que se envíe de nuevo para refactorizar
• Número máximo de argumentos que puede tomar una función antes de enviarla para refactorizar
• Algunas líneas de comentarios antes de que una función comience explicando brevemente lo que hace, si el cuerpo debe exceder una página de código en pantalla; dejando cómo se logra el objeto al código en el cuerpo de la función

Cuando estoy leyendo el código de otros (lenguaje C en su mayoría), si los nombres de variables / funciones no son intuitivos en el contexto del proyecto o si exceden los cinco niveles de sangría o las funciones toman más de seis o siete argumentos o una función se ejecuta por más de dos o tres páginas en pantalla, se hace muy difícil leer y entender el código. Cuando se le pide que realice mejoras / trabajos de mantenimiento, solo aumenta la dificultad. Me hace desear gofmtque el programa se escriba para cada proyecto (o incluso el idioma) y que cada archivo de código fuente se ejecute a través de ese programa antes de que se comprometa en el proyecto.

Me gusta la Guía de estilo de JavaScript de Google .

Es conciso en sus directrices pero tiene detalles si los necesita.

Código autodocumentado (comentarios, nombres de variables, nombres de funciones, etc.)