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

34

¿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.?
Cruzar
fuente

Respuestas:

40

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. .

dsimcha
fuente
3
Absolutamente. Cada artículo en un estándar debe tener la justificación especificada explícitamente.
AShelly
44
A veces no hay una buena razón para elegir, pero es deseable que todos hagan lo mismo. No sé por qué todos conducimos a la derecha, para usar la analogía de un automóvil, pero es mucho mejor que la mitad a la derecha y la otra a la izquierda.
David Thornley
99
@David: Esa es una razón perfectamente legítima para tener un estándar de codificación. Si esa es la razón, entonces simplemente debería expresarse como tal, es decir, "Razón: para mejorar la coherencia de la base de código".
dsimcha 29/10/10
De hecho, lo más importante acerca de un estándar de codificación es que no es uno. Lo que hay allí es realmente secundario.
Jörg W Mittag
20

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

Fede
fuente
1
Estoy totalmente de acuerdo!
matiash
2
En mi humilde opinión, eso es lo único que merece estar en un estándar de codificación.
P Shved
2
En mi humilde opinión, ese es un excelente ejemplo de lo que un estándar de codificación no debería cubrir.
Bjarke Freund-Hansen
@bjarkef, ¿prefieres el código mixto de tabulación y espacios?
Jé Queue
19

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

Rachel
fuente
3
LPSZ * lppsz_CPP_MrKim_ClassOfStudents [] [];
Mateen Ulhaq
3
-1: Este es exactamente el tipo de detalle de bajo nivel que hace que los desarrolladores ignoren los estándares. También podría exigir que todos usen corbatas.
TMN
2
@ TMN: La falta de convenciones de nomenclatura es el tipo exacto de cosas que hace que los desarrolladores se desesperen de entender el código. No tienen que ser quisquillosos, pero algunas pautas generales serán de gran ayuda.
David Thornley
1
@Rachel: Sí, teníamos que "todas las propiedades booleanas deben comenzar con el estándar 'Es'". Herido con propiedades como IsCanUpdatey IsHasChildren. 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.
TMN
1
Es por eso que creo que debería incluir Directrices, no Reglas, sobre cómo nombrar sus objetos. Los nombres exactos aún se dejan a los desarrolladores. Editaré mi respuesta.
Rachel
10

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.

Macneil
fuente
Convenido. La otra parte que agregaría es que si lo está dejando vivo como una advertencia, entonces debe abordarse cambiándolo o suprimiendo la advertencia. De lo contrario, las advertencias se vuelven inútiles rápidamente (demasiadas en un proyecto grande) y es mejor que las apague. En VS, prefiero ver que las advertencias rompen la construcción y te obligan a lidiar con ellas.
MIA
¿No es esto algo que debes poner en tu archivo MAKE y no en un estándar?
Bjarke Freund-Hansen
@bjarkef: en última instancia, las opciones irán al Makefile, sí. Pero el punto de ponerlo en el estándar es estandarizar lo que debe abordarse. Por ejemplo, ¿deberían los desarrolladores crear siempre ID de serialización? Depende del equipo decidir si esto debe ser obligatorio o ignorado.
Macneil
@bjarkef: Claro, pero es bueno tenerlos en una referencia estándar para cuando comienzas un nuevo proyecto y tienes que escribir un nuevo archivo MAKE (o tu nuevo proyecto usa algo más que Make para su herramienta de compilación).
TMN
9

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
usuario2567
fuente
Los requisitos relativos a la cobertura de pruebas unitarias son una de las mejores cosas que pueden entrar en los estándares de codificación.
Adam Crossland
Con respecto a la cobertura de prueba: ¿Por qué solo el 80%? ¿Es este un ejemplo de la regla 80/20 nuevamente, donde en su experiencia ese 20% final requeriría un 100% más de esfuerzo para lograrlo? Además, ¿qué tipo de cobertura? [por ejemplo, ¿cobertura de estado de cuenta? Cobertura de la función? Cobertura de decisión? Condición de cobertura?]
Macneil
@ Macneil: sí, algo así. Descubrí que el 80% es "suficientemente bueno" para la mayoría de las clases y es un buen número. Una vez intenté alcanzar el 95% y fue una verdadera pérdida de tiempo. Por supuesto, si es fácil alcanzar el 100% para algunas clases, adelante
Entonces, ¿es esa declaración la cobertura? Parece que muchas herramientas no te dan más que eso. ¿Qué herramienta usas?
Macneil
Uso TestDriven.net con nCover integrado
7

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.

AShelly
fuente
6

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 .

Alan Pearce
fuente
4

¿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.

Rodney Gitzel
fuente
3

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

Dima
fuente
3

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.

GruñónMono
fuente
¿Cómo se verifica el tipo y tamaño de fuente?
Jé Queue
@xepoch, fue visualmente en ese punto. La razón por la que estaba en el estándar de ese tiempo era doble: era más fácil para el gerente en el momento de leer cuando se imprimió y se especificó el tipo de letra para solucionar los problemas de espacio (se exigió el espacio monoestable), por lo que cada columna de caracteres alineado.
GrumpyMonkey
oh señor: me recuerda el estándar que exigía el número de líneas vacías entre todo, entre los métodos con los que estoy satisfecho (ya que muchos espacios en blanco ayudan a diferenciar los bloques grandes) pero antes y después de cada bloque de comentarios, y después de la declaración fn pero antes del código de función, etc ... al final se volvió un poco tonto.
gbjbaanb
2

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ó.

TMN
fuente
2

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.

Matthieu M.
fuente
2

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.

revs Conrad Frix
fuente
Donde estoy trabajando actualmente, todas las interfaces tienen que implementarse explícitamente y es un gran dolor. Si tan solo hubieran leído las Directrices de diseño del marco antes de escribir su estándar de codificación.
Martin Brown
1

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.)

Rory Alsop
fuente
+1: Esto y las consideraciones de subprocesos múltiples a menudo son desconocidas o mal entendidas, incluso por desarrolladores experimentados.
TMN
1

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.

usuario281377
fuente
1

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.

revs bjarkef
fuente
1

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.
Mag20
fuente
0

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.

vpit3833
fuente
Ha habido embellecedores de código por años. Google uno para tu idioma, encontrarás uno.
gbjbaanb
-1

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

aggietech
fuente