¿Por qué el tío Bob sugiere que los estándares de codificación no deberían escribirse si puedes evitarlo?

Mientras leía esta pregunta , la respuesta más votada citaba al tío Bob sobre los estándares de codificación , pero este consejo me confundió:

3. No los escriba si puede evitarlo. Más bien, deje que el código sea la forma en que se capturan los estándares.

Esto rebotó en mi cerebro, pero no pude encontrar un lugar donde quedarme. Si una nueva persona se une al equipo, o los estándares de codificación cambian, ¿no podría haber confusión de información?

¿Por qué no debería escribir un estándar de codificación?

Hay unas pocas razones.

1. Nadie lee la documentación.
2. Nadie sigue la documentación, incluso si la leen.
3. Nadie actualiza la documentación, incluso si la leen y la siguen.
4. Escribir una lista de prácticas es mucho menos efectivo que crear una cultura.

Los estándares de codificación no se refieren a lo que las personas deberían hacer, sino a lo que realmente hacen. Cuando las personas se desvían de los estándares, esto debería ser recogido y cambiado a través de un proceso de revisión de código y / o herramientas automatizadas.

Recuerde, el objetivo de los estándares de codificación es hacernos la vida más fácil. Son un atajo para nuestro cerebro para que podamos filtrar las cosas necesarias de las cosas importantes. Es mucho mejor crear una cultura de revisión para hacer cumplir esto que formalizarlo en un documento.

Hay otra interpretación. No creo que sea lo que quería decir tío Bob, pero vale la pena considerarlo.

No capture estándares de codificación en un documento. Captúrelo en código al tener un proceso automatizado que verifique que se cumplen los estándares .

No confíe en que las personas hagan referencia a un documento, pero al mismo tiempo, no confíe en que las personas interpreten el código que ya existe e identifiquen qué es una convención y qué es una coincidencia.

Incorpora algo como Checkstyle en tu build de commit. Esto puede hacer cumplir las reglas básicas como los estándares de formato y nomenclatura, y luego, en lugar de gastar esfuerzo mental al considerar el estilo, todo eso puede descargarse en un proceso tonto que al menos se garantiza que sea exhaustivo.

Si es importante, defina estrictamente qué es lo que desea y falle si está mal.

La gente pasa por alto el verdadero propósito de un documento de estándares de codificación, que es resolver disputas .

La mayoría de las decisiones en el estándar de codificación tendrán un efecto muy pequeño en la legibilidad y la productividad. Especialmente si adopta el estilo "normal" para el idioma, y ​​los diseñadores de idiomas comienzan a darse cuenta de que esto debería ser parte de la especificación (por ejemplo, Ir).

Debido a que son tan triviales, los argumentos pueden ser realmente acalorados y continuar sin parar, causando un daño real a la productividad y la cohesión del equipo. O puede ocultar su historial de cambios con un reformateo interminable entre los estilos preferidos de dos o más personas.

Tener un estándar escrito termina el argumento. Los gerentes pueden señalarlo y desviar la insatisfacción hacia el documento. Puedes discutir con un pedazo de papel pero no te va a escuchar.

(Ver también La tiranía de la falta de estructura )

Porque los comentarios son mentiras .

El estándar de codificación es un gran comentario sobre cuál debería ser el código. El código en sí es la última fuente de verdad. La verdad en este caso no es el comportamiento del código, es el estilo en el que se expresa. Si sus estándares ya no se reflejan en su código, tiene mucho trabajo por delante.

El tío Bob ve un comentario como una falla personal del programador, porque demuestra que no logró expresar el propósito del fragmento de código con el lenguaje de programación en sí. Del mismo modo, un documento estándar es una falla al expresar un estilo coherente en la base del código.

Los nuevos programadores deberían pasar tiempo mirando el código, no pasar días leyendo un documento de estándares de varios capítulos (he tenido que hacer esto, suspiro).

Un documento de estándares no es una mala idea, pero he estado en talleres de programación donde mantener los documentos de estándares era el trabajo a tiempo completo de alguien. Por favor, si debe mantener un documento estándar, guárdelo en una página. Pero si ya tiene un código, ¿nadie debería poder armar el mismo documento en menos de un día?

Tener estándares de código es importante. Tener un documento que dicta lo que son no lo es.

¿Por qué el tío Bob sugiere que los estándares de codificación no deberían escribirse si puedes evitarlo?

Si está preguntando razones detrás de su opinión, entonces puede tener una respuesta solo si él publicará una respuesta aquí ( nuestra opinión es irrelevante), sin embargo ...

¿Por qué no debería escribir un estándar de codificación?

Si está preguntando si tiene razón al respecto: déjeme ser el único impopular (hasta ahora) que diga que no tiene ninguna razón para evitarlo.

ESCRIBIRLO ABAJO . Sin embargo, intentaré explicar mis razones ...

David sugirió en un comentario que el punto principal de la respuesta de Stephen no es por qué no debería escribir documentos, sino en qué forma están. Si las pautas se formalizan en las herramientas (no solo en la revisión manual del código), entonces puedo estar de acuerdo (cuando la ley no requiere otra cosa). Tenga en cuenta que desafortunadamente las herramientas no pueden verificar todo (la teoría de la computación no es nuestra amiga) a menudo porque están limitadas a una unidad o paquete de traducción específico o como su idioma favorito llame a un límite .

Sin embargo, la redacción del tío Bob no me hace pensar que está hablando de eso.

¿Puedo estar en desacuerdo con un experto tan alto? Lo hago, para casi todos los puntos en la publicación citada (ver también la segunda parte de esta respuesta para más detalles). Tratemos de entender por qué (suponiendo que ya sepa que las pautas de codificación no son solo problemas menores de formato ).

• En algunas circunstancias, la ley exige normas de codificación escritas.
• Leo la documentación y estoy seguro de que no estoy solo. Los miembros del equipo pueden cambiar con el tiempo, el conocimiento no puede estar en una base de código de 5 a 10 años o en la mente de los miembros del equipo. Las organizaciones deberían despedir a las personas que no siguen las pautas internas.
• Los estándares de codificación, una vez que hayan sido aprobados , no cambiarán con frecuencia y si lo desea, debe saberlo. Si los estándares cambiaron, entonces su documentación (en el código) está desactualizada porque todo su código no sigue el nuevo estándar. Reformatear / refactorizar puede ser lento, pero siempre debe seguir una guía autorizada por escrito .
• Es mejor leer un documento de 5 páginas que inspeccionar 10 / 20K LOC para extrapolar una regla (que puede comprender erróneamente, por cierto), no hay duda al respecto.
• Es irónico que alguien que escribió muchos libros sobre principios de diseño y estilo de codificación sugiera que no debe escribir sus propias pautas, ¿no es mejor si nos deja con algunos ejemplos de código? No, porque las pautas escritas no solo le dicen qué hacer, sino también otras dos cosas de las que carece el código: qué no hacer y razones para hacerlo o no.

La "programación de autoorganización gratuita" es buena para un chico ninja de 16 años, pero las organizaciones tienen otros requisitos :

• La calidad del código debe otorgarse (y definirse) a nivel de empresa: no es algo sobre lo que un solo equipo pueda decidir. Es posible que ni siquiera tengan las habilidades para decidir qué es mejor (¿cuántos desarrolladores, por ejemplo, tienen todas las habilidades requeridas para revisar MISRA o incluso simplemente entender cada regla?)
• Los miembros pueden moverse a través de diferentes equipos: si todos siguen los mismos estándares de codificación, entonces la integración es fluida y menos propensa a errores.
• Si un equipo se autoorganiza, los estándares evolucionarán con el tiempo cuando los miembros del equipo cambien; entonces tendrá una enorme base de código que no sigue los estándares aceptados actuales .

Si está pensando en las personas antes del proceso , solo puedo sugerirle que lea sobre TPS: los seres humanos son una parte central de Lean, pero los procedimientos están altamente formalizados.

Por supuesto, una organización pequeña con un solo equipo puede dejar que el equipo decida los estándares a adoptar, pero luego debe anotarse. Aquí en Programmers.SE puede leer publicaciones de Eric Lippert: Supongo que todos estamos de acuerdo en que es un desarrollador experimentado, cuando trabajó para Microsoft tuvo que cumplir con sus pautas escritas (incluso si algunas reglas pueden ser incorrectas , no aplicables o inútiles) a él.) ¿Qué pasa con Jon Skeet? Las pautas de Google son bastante estrictas (y muchas personas no están de acuerdo con ellas), pero debe cumplirlas. ¿Les falta el respeto? No, probablemente trabajaron para definir y mejorar tales pautas, una empresa no está compuesta por un miembro (o un equipo) y cada equipo no es una isla .

Ejemplos

• Decidió no usar herencia múltiple y clases anidadas en C ++ porque los miembros reales del equipo no lo entienden bien . Más tarde, alguien que quiera usar herencia múltiple debe explorar todo el 1M LOC para ver si alguna vez se ha usado. Es malo porque si las decisiones de diseño no están documentadas, debe estudiar toda la base de código para comprenderlas. E incluso entonces, si no se ha utilizado, ¿es porque está en contra del estándar de codificación, o está permitido, pero simplemente no hubo situaciones anteriores en las que la herencia múltiple fuera una buena opción?
• En C # había sobrecargado los métodos para proporcionar parámetros predeterminados porque su base de código comenzó cuando los parámetros opcionales no estaban disponibles en C #. Luego cambió y comenzó a usarlos (refactorizando el código antiguo para usarlos cada vez que tenía que modificar tales funciones). Incluso más tarde, decidió que los parámetros opcionales son incorrectos y comienza a evitar usarlos. ¿Cuál es la regla que te dice tu código? Es malo porque el estándar evoluciona, pero la base de código es más lenta y si es su documentación, entonces está en problemas.
• Jon pasó del equipo A al equipo B. Jon tiene que aprender un nuevo estándar; mientras aprende, probablemente introducirá errores más sutiles (o, si tiene suerte, solo tomará mucho tiempo comprender el código existente y hacer que la revisión del código sea más larga).
• El equipo A pasa a una base de código que anteriormente pertenecía al equipo B. Tiene estándares de codificación completamente diferentes. ¿Volver a escribir? ¿Adaptar? ¿Mezcla? Todos ellos son igualmente malos.

Tío Bob

Déjelos evolucionar durante las primeras iteraciones.

Es cierto, hasta que no tenga un estándar y su organización le haya asignado la tarea de construir uno.

Permítales ser específicos del equipo en lugar de específicos de la compañía.

No, por todas las razones explicadas anteriormente. Incluso si piensas formalizar solo el formateo de código (lo menos útil que quieras formalizar), todavía tengo memoria de guerras interminables (e inútiles) sobre el formateo. No quiero vivirlos una y otra vez, configúrelo de una vez por todas.

No los escriba si puede evitarlo. Más bien, deje que el código sea la forma en que se capturan los estándares.

No, por todas las razones explicadas anteriormente (por supuesto, a menos que refactorice todo su código de una sola vez cuando cambien las pautas). ¿Quieres dejar tu código tal como está? ¿Cómo inspecciona la base de código para comprender las pautas actuales ? ¿Busca por antigüedad del archivo y adapta su estilo de codificación a la antigüedad del archivo de origen?

No legisles un buen diseño. (por ejemplo, no le digas a la gente que no use goto)

Es cierto que las pautas deben ser cortas o nadie las leerá. No repitas lo obvio.

Asegúrese de que todos sepan que el estándar se trata de comunicación y nada más.

No solo, un buen estándar se trata de calidad a menos que desee tener un estándar solo sobre detalles menores .

Después de las primeras iteraciones, reúna al equipo para decidir.

Vea el primer punto y no olvide que un estándar de codificación suele ser un proceso que tardó muchos años en desarrollarse y refinarse: ¿pocas iteraciones, tal vez con desarrolladores junior? De Verdad? ¿Desea confiar en la memoria de un miembro senior (si lo hay)?

Tres notas:

• En mi opinión, los inconvenientes son más graves con algunos lenguajes que con otros, por ejemplo, en C ++, un estándar a nivel de empresa es aún más necesario que en Java.
• Es posible que este razonamiento no se aplique por completo (y los motivos del tío Bob pueden ser menos extremos ) si está trabajando en una empresa muy pequeña en la que solo tiene un equipo pequeño.
• Estás contratado (como equipo) y trabajarás solo con un nuevo proyecto, luego lo olvidarás y seguirás adelante. En este caso, es posible que no le importe (pero su empleador debería ...)

1. Para ser útil, un estándar de codificación no debe hablar sobre cuestiones de fondo; solo cuestiones de estilo. Debe especificar solo aquellas cosas que son arbitrarias y ambiguas. por ejemplo, colocación de llaves, profundidad de sangría, espacios frente a pestañas, convenciones de nomenclatura, etc.
2. Las cuestiones de estilo son locales, no globales. Cada equipo debe adoptar su propio estilo peculiar, acorde con su tarea y su personalidad. Esto mantiene los estándares simples y livianos. Los estándares corporativos se sobrecargan con todas las posibles consideraciones, configuraciones y excepciones.
3. Dentro de un equipo, la única razón para escribir un documento de estilo de codificación separado es si el código producido por el equipo no cumple con el estándar. En cuyo caso no tienes estándar. Para ser efectivo, el estándar debe ser expresado por el propio código. Y si eso es así, no hay necesidad de un documento separado.
4. En los sistemas heredados, los equipos y estilos cambian con el tiempo. No hay nada de malo en eso. El código antiguo tendrá un estilo más antiguo. El código más nuevo tendrá un estilo más nuevo. El equipo debe conocer los estilos y sus edades. Siempre que se escriba un nuevo código, debe estar en el nuevo estilo, sin importar en qué parte del código se encuentre.

¿Por qué no debería escribir un estándar de codificación?

Hay muchas razones para esto. Aquí hay algunas consideraciones:

1. ¿Cuánto tiempo pasan las personas "aprendiendo" los estándares del código solo para tener mucho tiempo para que todo el equipo revise, discuta, documente, revise ... etc. estándares del código? Esto es como discutir constantemente su "Manual del Empleado": ¿con qué frecuencia aparece en la agenda de una reunión de equipo?

2. Cuando un proyecto es financiado / archivado / etc. entonces las pocas personas que quedan generalmente no pueden seguir adhiriéndose (o tal vez ni siquiera han leído) los estándares. Lo siguiente que sabes es que, de todos modos, todo ese esfuerzo para "mantener limpio el código" se desperdició.

3. Si el proyecto se detiene o se presenta un nuevo cliente potencial, es muy probable que la persona ignore por completo las reglas anteriores y quiera hacerlo de una nueva manera. Nuevamente, ¿qué se ganó codificando estándares?

Debes asegurarte de leer # 6:

Después de las primeras iteraciones, reúna al equipo para decidir.

En otras palabras, cuando llegue el momento de comenzar un proyecto, simplemente siga la corriente por un tiempo. Luego discuta las reglas generales de los estándares de codificación que el equipo actual está usando, y básicamente sígalas. De esa manera, maximiza el esfuerzo que se necesita para mejorar el producto y minimiza el esfuerzo necesario para escribir, revisar y documentar el "azúcar sintáctico" que se utilizó para obtener el código ejecutable.

Muy pocos equipos obtienen enormes beneficios de los estándares de codificación. Por lo general, "legibilidad" es demasiado vago - y la mayoría de los desarrolladores no se benefician en gran medida de exactas reglas sobre el espaciamiento, nuevas líneas, etc., pero se puede evitar constantemente molestos desarrolladores por tener al menos un par de reglas.

Otra respuesta que no creo que se haya dicho con suficiente claridad es que también significa que las personas no siguen las reglas a ciegas. Significa que las personas tienen que presentar justificaciones reales para sus decisiones de diseño y convenciones de codificación, en lugar de solo depender del hecho de que se ha escrito para justificarlo.

En primer lugar, que yo sepa, el tío Bob es una persona de Java, esto es muy importante para entender lo que dice.

Cuando trabajo en un equipo Java o C #, si el código actual ha sido escrito por desarrolladores experimentados, es fácil para mí elegir el estilo de codificación y seguir el ritmo. Si no estoy dispuesto a hacerlo, tal vez no era la persona adecuada para el trabajo ... Si no hay revisión de código o programación de pares para recogerme cuando no sigo con el estilo, entonces la compañía tiene un ¡Un problema mayor que la forma en que nombro los campos de miembros!

Tanto Java como C #, junto con la mayoría de los lenguajes modernos, se han definido para que haya pocas trampas "simples" en las que pueda caer un programador.

Sin embargo, cuando comencé a programar, estaba usando C (y luego C ++). En C puedes escribir código como

if (a = 3);
{
   /* spend a long time debugging this */
}

El compilador no dará un error, y eso es difícil de detectar cuando se lee mucho código. Sin embargo, si escribes:

if (3 = a)
{
   /* looks odd, but makes sense */
}

El compilador da un error, y es fácil cambiar el código 3 == a. Del mismo modo, si el estándar de codificación no permite =ser utilizado dentro de una ifcondición o " ifdeclaración vacía ", entonces se puede usar un verificador de código como parte del sistema de compilación para rastrear este error.

Mis puntos de vista sobre los estándares de codificación cambiaron mucho cuando me alejé de C / C ++: solía gustarme los estándares de codificación que se aplicaban estrictamente y tenían muchas páginas. Ahora creo que solo necesita enumerar las herramientas que se utilizan y obtener un acuerdo informal entre los miembros del equipo original en algunas convenciones de nomenclatura. Ya no vivimos en un mundo de equipos de más de 30 desarrolladores que escriben aplicaciones en C / C ++ ...

Hay una razón por la que nunca me gustó JScript, y creo que TypeScript es lo mejor que le ha pasado al desarrollo web durante años. Espero que los desarrolladores de IU web todavía necesiten estándares de codificación debido a los defectos en el diseño de HTML / CSS / JScript, etc.

Que la fuente sea el estándar de codificación autodocumentado implica dos cosas.

1. Las personas deben consultar el código base y revisarlo para convertirse en colaboradores competentes. Esto es increíblemente importante. Leer las pautas de codificación es una pérdida de tiempo en comparación con sumergirse en la base del código.
2. Reconoce que las diferencias menores no son importantes. Es importante acordar y comprender los principios básicos. Mantener un estilo consistente no se persigue como l'art pour l'art. No permite que los no creativos molesten y distraigan a otras personas. Se trata de facilitar la comunicación a través del código en un equipo.

Un documento de estándares de código bien actualizado y bien escrito puede ser muy útil, pero generalmente este no es el caso. El documento de estándares no refleja los estándares de codificación reales utilizados por la compañía, ya que es muy difícil crear un buen documento de estándares y aún más difícil mantenerlo actualizado.

En lugar de tener un documento de estándares de codificación pobre y engañoso, es mejor no tener ninguno y dejar que el código mismo represente esos estándares. De cualquier manera, la parte más importante es aplicar los estándares en el código, y esto requiere mucho más que un simple documento. La motivación, los procesos, los entrenamientos, las herramientas, etc. son mucho más importantes.

Una cosa muy importante que no se ha establecido con suficiente claridad es que los estándares de codificación son como el lenguaje: evolucionan. Un estándar de codificación escrito se interpone en el camino de esto, y si no lo hace, está continuamente desactualizado e inútil.

No tener un estándar de codificación definido no es tan malo. Si realiza revisiones por pares en el check-in, cada vez que algo que no cumple con el estándar de codificación ingresa al repositorio, eso significa que 2 personas lo pensaron * y decidieron que el beneficio de esta variación supera la inconsistencia con el resto del código.

No tener un estándar escrito también elimina la burocracia que evitaría que un equipo de una empresa intente una nueva variación del estándar de codificación para un nuevo proyecto, ya sea porque quieren probar algo o tal vez porque un estándar diferente tiene aplicaciones prácticas en algunas de las herramientas automatizadas que usan.

Escribir un estándar tiene una tendencia a eliminar más flexibilidad de lo que se pretendía originalmente, al tiempo que consume bastante tiempo que podría dedicarse a otras cosas. No digo que nunca debas escribir estándares de codificación, los estándares escritos ciertamente tienen sus beneficios, especialmente si los equipos que trabajan en diferentes ubicaciones trabajan en la misma base de código.

Muy relacionado: Evolución en los estándares de codificación, ¿cómo los maneja?

* Si las personas no piensan mientras revisan el código por pares en el check-in, sus problemas son mucho más grandes que los estándares de codificación.

Cambiarlos se convierte en un obstáculo importante, y las personas se adherirán con seguridad a la letra de la ley en lugar de comprometerse con el cerebro y hacer lo correcto.

Llegará el día en que parte del estándar no sea útil y empeore el código. Algunas personas se adherirán al estándar, porque está escrito y son seguras, y porque las reglas están ahí para ser seguidas. Las personas que desean escribir un buen código en lugar de un código que cumpla con los estándares se sentirán frustradas y enojadas. Habrá argumentos y desacuerdos, mientras que si el estándar no fuera escrito, habría exploración y discusión.

Creo que muchas publicaciones aquí son un estándar de codificación confuso con una guía de estilo .

Asegurarse de que los módulos desarrollados por diferentes equipos tengan las mismas opciones de compilación y ABI es un tipo diferente de cuántos espacios están sangrados.

Deben documentarse cosas como la forma adecuada de estructurar #incluir archivos y no contaminar el espacio de nombres global en un archivo de encabezado para que puedan usarse como una lista de verificación durante la codificación inicial y las revisiones de código.

En particular, "no uses XXX porque causa problemas de compatibilidad con YYY" no es algo que verías por ejemplo al seguir otro código, ya que no está allí. Por lo tanto, deje que el código sea la forma en que se capturan los estándares, puede que no esté claro o que falte por completo para algunos tipos de estándares, por lo que este no puede ser un plan universal.

Algo gravemente dominante e importante como no usar excepciones o no usar newen ciertos sistemas integrados no puede dejarse simplemente como conocimiento cultural común, ya que "la información es cultural (solo)" contradice los principios fundamentales de los estándares de fabricación como ISO-9000, que el El desarrollador de estos sistemas integrados está utilizando (por ejemplo, para aplicaciones automotrices). Estas cosas importantes deben documentarse, firmarse y archivarse de manera formal.

Pero eso se aplica a la codificación , no al estilo .

Los inventores de C y C ++ muestran, por ejemplo, el uso de nombres en minúsculas y no CaMelCaSe. Entonces, ¿por qué tantos desarrolladores no siguen el ejemplo implícito de la fuente? ¿No debería ser el estilo de la biblioteca estándar y los materiales de enseñanza canónicos el estilo implícito a seguir?

Mientras tanto, las personas hacen seguir el ejemplo de los encabezados de biblioteca estándar para las cosas que no deben ser copiados, al igual que el uso de __Uglylos nombres de los parámetros macro y el archivo de inclusión patrón no repetición.

Por lo tanto, tener cosas a menudo no se considera un estilo importante o, por el contrario, tener ejemplos puede no ser claro en cuanto a lo que no se debe seguir en el código del proyecto. Ambos son contraejemplos de la tesis de que "estilo" (o convenciones de codificación) es mejor dejarlo implícito.