¿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.?
coding-standards
Cruzar
fuente
fuente
Respuestas:
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. .
fuente
Tabs vs Spaces! Recibo actualizaciones locas cuando uno de mis colegas accidentalmente ingresa muchas pestañas para que los espacios cambien al repositorio
fuente
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
fuente
IsCanUpdate
yIsHasChildren
. Claro, está mal, pero fue decretado en el estándar. Y este es mi punto: una vez que comienzas a especificar estas cosas, debes asegurarte de cubrir todas las bases, o la gente se topará con algo que el estándar no cubre, o cubre mal, y luego escriben algo que está mal, o comienzan a ignorar el estándar. De cualquier manera, el equipo pierde.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.
fuente
Algunos estándares que me gustan (sé que hay muchos de ellos, pero esos son los que prefiero):
fuente
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
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:
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
static
yvolatile
, etc.Reglas sobre macros de preprocesador y otras características del lenguaje fácilmente abusables.
fuente
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 .
fuente
¿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.
fuente
Un procedimiento para revisiones de código para hacer cumplir el estándar. Ah, y para encontrar errores también.
fuente
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.
fuente
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ó.
fuente
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 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:
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:
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:
Obviamente, cambiar una regla significa obtener el "avance" de los líderes.
fuente
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)
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.
fuente
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.)
fuente
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.
fuente
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.
fuente
Los estándares de codificación son realmente varios elementos:
Convenciones de codificación
Mejores prácticas
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
Entorno de codificación
fuente
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
gofmt
para formatear el texto del programa a un formato. Cualquier debate sobre el formato de codificación simplemente resultará como un parche para las fuentes degofmt
.En cuanto a lo que debe tener el formato,
if
, cuerpo de la función, bloques de instrucciones para cualquier otro propósito,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
gofmt
que 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.fuente
Me gusta la Guía de estilo de JavaScript de Google .
Es conciso en sus directrices pero tiene detalles si los necesita.
fuente
Código autodocumentado (comentarios, nombres de variables, nombres de funciones, etc.)
fuente