¿Cómo podría saber si ha escrito código legible y fácil de mantener?

336

¿Cómo se podría saber si el código que se ha creado es fácilmente legible, comprensible y mantenible? Por supuesto, desde el punto de vista del autor, el código es legible y mantenible, porque el autor lo escribió y lo editó, para empezar. Sin embargo, debe haber un estándar objetivo y cuantificable por el cual nuestra profesión pueda medir el código.

Estos objetivos se cumplen cuando se puede hacer lo siguiente con el código sin el asesoramiento experto del autor original:

  • Es posible leer el código y comprender en un nivel básico el flujo de la lógica.

  • Es posible comprender a un nivel más profundo lo que está haciendo el código para incluir entradas, salidas y algoritmos.

  • Otros desarrolladores pueden realizar cambios significativos en el código original, como la corrección de errores o la refactorización.

  • Uno puede escribir código nuevo, como una clase o módulo que aproveche el código original.

¿Cómo cuantificamos o medimos la calidad del código para saber que es legible, comprensible y mantenible?

usuario22815
fuente
154
Enlace obligatorio (por una vez, no a xkcd): osnews.com/images/comics/wtfm.jpg
Jerry Coffin
3
Simplemente diría que lo sabes cuando lo ves, pero este argumento era fundamentalmente defectuoso y vergonzoso, incluso en su forma original, no importa si se aplica al código fuente.
Konrad Rudolph el
66
"Por supuesto, en su punto de vista, su código es legible", ¡no es tan obvio!
UncleZeiv
24
Diría que lo sabes cuando lo veas unos meses después de que lo escribiste.
JeffO
2
@asfallows: le mostré un código a mi esposa, y ella pensó que era un código realmente malo, ¡porque podía leerlo! (Demasiadas palabras en inglés y no suficientes caracteres @ [! ^ $ & *) ...)
gnasher729

Respuestas:

370

Su compañero le dice después de revisar el código.

No puede determinar esto usted mismo porque, como autor, sabe más de lo que el código dice por sí mismo. Una computadora no puede decirle, por las mismas razones que no puede decir si una pintura es arte o no. Por lo tanto, necesita otro ser humano, capaz de mantener el software, para ver lo que ha escrito y dar su opinión. El nombre formal de dicho proceso es revisión por pares .

usuario1249
fuente
66
Nada supera las pruebas empíricas.
Ingeniero mundial
25
+1 Su audiencia más importante son sus compañeros que están inmersos, con usted, en conocer los porqués y cómo del problema en el que está trabajando y sus soluciones. Un buen código refleja la comprensión actual de su grupo de pares de esto. Asumiendo que el equipo es capaz, atento y abierto a nuevas ideas, "su compañero que le dice que es bueno / mantenible" es, en mi experiencia, una mejor definición por lejos que cualquier otra.
Doug T.
69
En mi experiencia, esto solo funciona cuando su colega sabe lo que es bueno y lo que es malo. De lo contrario, sonará así: "Deberías escribir esos códigos con el mismo método, es más fácil encontrar el código"
Rangi Lin
12
@RangiLin, bueno, tu colega puede tener razón.
11
@Rangi Tienes que trabajar con los colegas que tienes. si encuentran su código difícil, eso es un problema con su código. A más largo plazo, se puede educar a ellos, o tratar de obtener mejores colegas (se puede mover o se puede influir en el proceso de contratación) ... Oh, sí, y hacer siempre recuerda que puede que tengan razón.
MarkJ
220

A veces, la mejor manera de saberlo es volver al código que escribió hace seis meses e intentar comprender para qué fue escrito.

Si lo comprende rápidamente, es legible.

Alex en París
fuente
28
Sí, eso suena bien (y es cierto), pero no es un enfoque muy bueno para decidir qué / cómo hacer hoy ...
Michael Durrant
10
Disección sugiere que está tomando un tiempo y hay que hacerlo con cuidado ...
deworde
3
Podría reducir el plazo para volver a visitarlo hasta un mes, o incluso menos, para una primera visita. Creo que depende de la complejidad del proyecto y el dominio, así como de su enfoque mental. Me parece que en seis meses, me distraigo al ver oportunidades de refactorización u optimización utilizando herramientas o técnicas que aprendí desde que escribí el código, en lugar de la legibilidad real.
Chris Bye
1
@MichaelDurrant Cada vez que revise el código antiguo, encontrará piezas que deberían haberse escrito de manera diferente y luego lo tendrá en cuenta para el código que está escribiendo "hoy". Sí, lleva tiempo aprender a escribir un buen código.
dj18
1
@MichaelDurrant todavía lo es, ya que puedes aprender qué cosas poco claras estabas haciendo hace seis meses y no hacer esas cosas hoy.
djechlin
94

Está:

  1. mantenible si puedes mantenerlo .
  2. fácilmente mantenible si alguien más puede mantenerlo sin pedirle ayuda
  3. legible si alguien más , al leerlo, comprende correctamente el diseño, el diseño y la intención

La prueba real para 1. es (como dicen Alex en París y quant_dev ) que puede recuperarlo después de unos meses haciendo otra cosa.

La prueba para 2. y 3. es que alguien más puede recogerlo y descubrir cómo extender o corregir su código mientras sigue el diseño de su diseño. Si no pueden entender el diseño, cómo se relaciona con el espacio del problema o cómo se pretende usar su código , en su lugar, piratearán una solución a través del grano.

Hay reglas generales, principios (es decir, reglas generales que alguien escribió muy bien y dio un nombre) y todo tipo de sugerencias que pueden guiarlo en la dirección correcta, o alejarse de las trampas comunes. Sin embargo, ninguno de ellos garantizará las cualidades que estás pidiendo.

Inútil
fuente
2
¿Qué tal si consideramos la cantidad de tiempo que dedicamos a corregir un error o modificar el comportamiento existente como factor de mantenibilidad? Se supone que un fragmento de código que requiere menos tiempo para hacer el mismo cambio es más fácil de mantener, ¿verdad?
VCD
1
Depende; a veces, hacer una modificación bien requerirá una refactorización (lo cual puede decirse que es necesario porque el código legible deja en claro que no está destinado a usarse así), lo que lleva más tiempo que piratear en un caso especial (cuyo código ilegible fomenta porque la intención no está clara )
Inútil
30

Si su código sigue los principios de SÓLIDO y SECO y tiene un buen conjunto de pruebas unitarias a su alrededor, probablemente sea mantenible.

¿Es legible? Léelo ¿Tienen sentido los nombres de métodos y variables? ¿Puedes seguir la lógica del programa sin problemas? Si la respuesta es sí, entonces el código es legible.

Oded
fuente
8
... y después de leerlo, entrégalo a otra persona para que intente leerlo.
jcmeloni
19
Esta no es una prueba particularmente buena. Muchas aplicaciones de esas reglas son subjetivas, y casi siempre puedes leer tu propio código justo después de haberlo escrito.
DeadMG
1
"Si la respuesta es sí, entonces el código es legible" ... por usted . Para ver si es legible para otros, otros deben intentar leerlo.
2
OMI, SOLID está sobrevalorado. Especialmente la 'S' Eso o todo el mundo lo lee mal.
Erik Reppen
Me he encontrado innumerables veces en código SECO y SÓLIDO y, sin embargo, horrible. Seguir los principios puede dar una falsa impresión de que lo que estás escribiendo no es basura.
Jakub Arnold
24

Leer cómo escribir un código que no se puede mantener: asegure un trabajo para toda la vida de Roedy Green, riéndose y aprendiendo.

... cómo escribir código que es tan difícil de mantener, que las personas que vienen después de usted tardarán años en realizar incluso los cambios más simples. Además, si sigue todas estas reglas religiosamente, incluso se garantizará una vida de empleo, ya que nadie más que usted tiene la esperanza de mantener el código ...

El ensayo le ofrece numerosos ejemplos de cómo escribir código incorrecto, utilizando muchos ejemplos divertidos. Continúa explicando cómo utilizar la falta de ortografía creativa , la reutilización de nombres , la muy apreciada técnica de reutilización de nombres globales como privados .

De manera humorística, el ensayo te enseña cómo evitar todos los ejemplos de códigos ilegibles e imposibles de mantener.

En realidad, me resultó difícil creer que alguien escribiría código con similitudes con los ejemplos en el texto. Fue entonces cuando estaba recién salido de la escuela. Pero, después de trabajar durante unos años, veo el código del texto todos los días ...

iikkoo
fuente
Consulte también waterfall2006.com/gorman.html. La refuctorización es el proceso de tomar un código bien diseñado y, a través de una serie de pequeños cambios reversibles, hacer que sea completamente imposible de mantener por nadie más que por usted mismo.
Sjoerd
22

A pesar de lo que parece, hay algunas medidas bastante objetivas que puede considerar. Libros como C ++ Coding Standards , Refactoring y Clean Code tienen largas listas de criterios para juzgar su código, analizando cosas como nombres significativos, tamaños de funciones, principios como acoplamiento y cohesión, diseño de objetos, pruebas unitarias, refinamiento sucesivo, etc.

La lista es demasiado grande para ser susceptible de una lista de verificación, pero lees el libro y eliges algunas cosas clave para trabajar, luego, después de varios meses, léelo nuevamente para mejorar aún más.

Karl Bielefeldt
fuente
44
+1 para el aprendizaje incremental y no tratar de ser perfecto de la noche a la mañana
dj18
19

La prueba está en el pudín. Observe lo que sucede después de entregárselo a una persona razonablemente competente. Si no necesitan hacer muchas preguntas relacionadas con la dificultad del código, has hecho un buen trabajo.

Esta fue una primera lección de mi carrera. Un mentor dijo: "Documente todo, para que pueda escapar del programa más adelante. Si no anticipa preguntas cuando las respuestas están frescas en su mente, tendrá que resolverlas cuando no lo estén".

MathAttack
fuente
10
Tenga en cuenta que las personas pueden abstenerse de hacer preguntas por temor a exponer su ignorancia. Incluso puede estar percibiendo a esas personas como "razonablemente competentes" en primer lugar debido a su tendencia a abstenerse de exponerlo. Por lo tanto, la falta de preguntas puede no ser algo bueno a menos que sepa que ambos están siendo sinceros.
Hermann Ingjaldsson
1
@HermannIngjaldsson - Bastante justo. Por supuesto, si no son competentes y algo se rompe, lo oirás pronto. "¡¡¡¡Ayuda!!!!"
MathAttack
esto parece simplemente repetir lo que se dijo en la respuesta principal
mosquito
17

Leí todas las respuestas y noté que nadie mencionaba la complejidad del código.

Existe una estrecha correlación entre la complejidad del código y la legibilidad / mantenibilidad. Existen numerosos algoritmos de puntuación de complejidad de código, pero solo hablaré sobre cómo funciona la puntuación de complejidad de McCabe.

Básicamente, la puntuación de McCabe lee su código y calcula la cantidad de "rutas" únicas que hay a través de él. Si usa McCabe como su numerador y líneas de código como su denominador, también obtendrá una muy buena aproximación de "legibilidad".

Si tiene 10 líneas de código, y hay 300 rutas a través de ese código, ese es un código bastante difícil de mantener (difícil de cambiar de manera segura y fácil), y probablemente no sea muy legible. Por el contrario, si tiene 300 líneas de código, pero solo hay una ruta (no tiene condiciones), es legible y fácil de mantener.

Sin embargo, donde McCabe cae es en este último ejemplo. Si tengo 300 líneas de código sin condiciones, hay una muy buena posibilidad de que haya hecho "copiar / pegar reutilizar", y obviamente eso tampoco es algo bueno. Por lo tanto, existen medidas de todo el sistema que aplica además de McCabe, como la detección de código duplicado o casi duplicado.

revs Joe Rounceville
fuente
2
Esta debería ser la respuesta. Medida. Otras respuestas son más una opinión que un hecho, si puedo entenderlo, ¿debe ser bueno? Primero mida usando análisis de complejidad, luego refactor humano para buscar duplicación, etc.
Jon Raynor
1
Su último párrafo que menciona los inconvenientes del puntaje de McCabe dividido por LOC tiende a invalidar toda la idea. Si necesita 300 rutas a través de su código, ¿por qué cree que hará que el código sea más fácil de usar para usar más líneas? Es como decir que si un libro presenta ideas complejas, debería ser un libro realmente grande en lugar de tratar de comunicarse de manera concisa. -1.
Comodín el
8

Un punto que compartiría es si el código está integrado en "módulos", y cuando digo eso quiero decir que puede cambiar una cosa en un módulo y hacer que funcione fácilmente con el conjunto. Elimina los efectos entre cosas no relacionadas. También:

  • El código es fácil de reutilizar.
  • Su código es flexible (esto se relaciona con la construcción de módulos)
  • SECO - No te repitas

Recomiendo leer, El programador pragmático.

jket
fuente
8

Algunas pruebas / indicadores:

  • Apaga el IDE. ¿Todavía puedes leer tu propio código? Cuando hay un error, ¿es bastante fácil rastrearlo a mano y descubrir en qué clase necesitarás un punto de interrupción para descubrir dónde está el problema? O cuando usa el IDE, ¿ni siquiera se molesta y pasa desde el principio?

  • La depuración a menudo se convierte en un juego de wack-a-mole donde arreglar un error crea 2+ más.

  • Desde la activación del gatillo hasta algo realmente útil que suceda, ¿cuántas llamadas de método toma? ¿Cuántos métodos pasan exactamente los mismos o la mayoría de los mismos parámetros exactos a otra llamada de método?

  • ¿Cuántos archivos tiene que abrir para agregar un nuevo método simple a una clase?

  • Piensa en patrones y prácticas que hayas adoptado. ¿Lo hiciste porque tenían perfecto sentido o porque alguien te convenció de que "es la única forma de hacerlo?" o porque lo querías en tu currículum o porque algún desarrollador de rockstar lo dijo.

Erik Reppen
fuente
3
Leer código sin un IDE parece tonto, especialmente como una medida de legibilidad. Este tipo de métrica da como resultado "soluciones" de estilo de notación húngara que realmente socavan la legibilidad al final.
rubenvb
8

¿Cómo se podría saber si el código que creó es fácil de mantener y leer?

Puede detectar código fácil de mantener y legible buscando estas propiedades:

  1. Los objetos, métodos y / o funciones siempre hacen una cosa.
  2. Los métodos y / o funciones son concisos (como en "breve pero completo").
  3. Los objetos, métodos y / o funciones hacen esencialmente lo que crees que deben hacer en función de sus nombres.
  4. El código destinado a la reutilización es realmente reutilizable.
  5. Por último, pero no menos importante, si puede realizar una prueba de unidad inmediata del código, es probable que haya escrito un código modular de responsabilidad única como mínimo.

¿Cómo sabríamos si hemos escrito código bastante desordenado e imposible de mantener? ¿Hay alguna construcción o pauta para saber si desarrollamos software desordenado?

  1. Si está leyendo un método y no es evidente cuál era la intención, esto es poco elegante en el mejor de los casos y probablemente imposible de mantener en el peor.
  2. Si no parece simple, probablemente no lo sea y eso es una señal de código que no se puede mantener o código que pronto se volverá imposible de mantener.
  3. Si hay una falta de simetría (consistencia) en toda la base de código, es probable que esté buscando código que no se pueda mantener.
wilmoore
fuente
No estoy de acuerdo con que su ejemplo de refactorización sea más claro. Estoy de acuerdo en que el código original necesita trabajo, pero en términos de claridad e intención de comunicación, creo que el original es mucho mejor. Soy muy sospechoso de cualquier refactorización que afirme que mejora la claridad al introducir regex.
Roy
1
@ Roy, sí, es justo. Probablemente nunca debería haber agregado esa muestra de código. De acuerdo, fue hace casi 3 años, pero incluso entonces, probablemente no debería haber usado PHP (me da pena solo mirarlo ahora), y no debería haber usado una expresión regular ya que es una de esas cosas que algunas personas puede mirarlo y obtenerlo de inmediato, pero para otros, no importa cuán sucinta sea, las expresiones regulares son un apagado inmediato. Voy a editar la respuesta y soltar el código de muestra. Gracias por el comentario.
Wil Moore III
¿Cómo puede un objeto hacer una cosa?
Koray Tugay
@KorayTugay Piénsalo de esta manera. Si un objeto describe más de un concepto cohesivo, tiene un olor.
Wil Moore III
6

En una sola palabra, experiencia .

Para comenzar, debe haber puesto en el terreno, por lo que no puedo recomendar más que los programadores deberían tomarse el tiempo para leer libros como Refactoring , que proporcionará algunas de las herramientas más esenciales en un arsenal de programadores que mejorarán su capacidad para mantener el código y Clean Code, que ha sido escrito por algunos de los talentos más reconocibles en nuestro campo, y que describe casi todo lo que necesita comprender para garantizar que su código sea limpio y legible.

Sin embargo, ninguna cantidad de lectura es un sustituto de la experiencia duramente ganada. Realmente debe haber trabajado con el código por un tiempo para apreciar completamente la diferencia que puede hacer la atención a la calidad del código. Al experimentar el placer de trabajar con código limpio y bien factorizado, así como el dolor de trabajar con espagueti de código, aprendes a comprender mejor lo que los autores de estos libros realmente intentaban enseñarte, pero lo haces en un contexto más amplio del código de producción en vivo real, donde la calidad de lo que haces realmente importa e impacta tu capacidad de trabajar fácilmente con tu código a diario.

También ayuda tener un buen mentor o un compañero con la experiencia para confirmar que está poniendo el esfuerzo en escribir código a un alto nivel. Esta es solo una de las razones por las que las revisiones de código pueden ser tan útiles. El uso de herramientas de verificación y formateo de códigos también puede ser una ayuda muy útil para garantizar que mantenga las cosas limpias. Sin embargo, nada se compara con la experiencia obtenida a través de años de software de escritura, de tal manera que automáticamente te encuentras escribiendo código que es limpio, legible y estructurado simplemente para facilitar el mantenimiento, y todo porque te has acostumbrado a aplicar las mejores prácticas. largo.

S.Robins
fuente
3

Sin ser puritano: prefiera el estilo funcional. La mayoría de los idiomas en estos días (.NET, Ruby, Python, Javascript, etc.) lo admiten y lo promueven (por ejemplo, LINQ, underscorejs).

Es extremadamente fácil de leer.

var recentTopCustomers = OrderList
    .Where(o => o.Date >= DateTime.Now.AddDays(-5))
    .Where(o => o.Amount > 1000)
    .OrderBy(o => -o.Amount)
    .Take(10)
    .Select(o => o.Customer);

Obliga a cada nodo a tener préstamos de intención única y enfocada a la claridad del propósito. Y debido a que cada tarea discreta está aislada, trivial, conectar y reorganizar nodos (operaciones) a diferentes fines es trivial. Esto se presta para facilitar el mantenimiento.

Mario T. Lanza
fuente
2

Código legible y mantenible: Código que, a primera vista, un programador puede comprender lo suficientemente bien como para poder:

  • reutilizarlo a través de su interfaz, o
  • depurarlo, o
  • Cambia su comportamiento. (agregar / eliminar una función), o
  • optimizarlo
  • Pruébalo

Esto se reduce a 'claridad'. es decir, ¿cuántas preguntas tiene que hacer el programador a un segmento de código en particular antes de estar seguro de que 'entiende lo que hace lo suficientemente bien' para lograr la tarea actual sin causar efectos secundarios inesperados?

El libro 'Code Complete, de Steve McConnell' entra en esto con gran detalle.

Revisa varias métricas que puede usar para determinar si el código es de buena calidad.

Vea un ejemplo aquí: http://books.google.co.uk/books?id=3JfE7TGUwvgC&lpg=PT376&pg=PT389#v=onepage&q&f=false

revs JW01
fuente
esto no parece agregar nada sustancial sobre los puntos hechos y explicados en respuestas anteriores
mosquito
Creo que una de las cosas más importantes que agrega es una referencia a Code Complete, que ninguna respuesta anterior menciona. Ese libro es uno de los libros más importantes e influyentes que se centra en escribir código legible y mantenible. Cualquiera que haya leído ese libro no necesitaría preguntar "¿Cómo sabría si ha escrito un código legible y fácil de mantener?".
JW01
... por lo tanto, en mi opinión, creo que lo mejor que alguien podría obtener si está realmente interesado en escribir código mantenible es leer ese libro. Por lo tanto, con muchos minutos de pensamiento cuidadoso (que a menudo es mucho más pensamiento que los moderadores de SO), creo que esta no es solo una respuesta adecuada a la pregunta del OP, sino la mejor .
JW01
2

Minimizar los efectos secundarios (idealmente no tener ninguno)

Una función que causa 3 cambios en estados fuera de su propio alcance es mucho más difícil de razonar y mantener que una que simplemente ingresa algo y genera algo más. No solo puede saber qué hace la función, debe recordar lo que hizo y cómo afecta a todas las demás funciones relevantes.

Para OOP, minimizar los efectos secundarios también significa clases con menos miembros, y especialmente menos miembros que pueden modificar el estado de la clase, ya que las funciones de los miembros pueden modificar estados más allá de los suyos y tener efectos secundarios (pueden manipular los elementos internos de la clase, por ejemplo). También significa clases con menos miembros de datos propios para que haya menos estado para que esos métodos puedan manipularlos y menos efectos secundarios que puedan causar.

Como un ejemplo simple, imagine tratar de diseñar una estructura de datos elegante que pueda mantener un sortedestado que utiliza para determinar si se realizan búsquedas binarias o lineales. En tal caso, podría ser útil separar el diseño en dos clases. Llamar sorteda la clase no ordenada podría devolver una estructura de datos de otra clase que siempre mantiene su contenido ordenado. Ahora tiene menos efectos secundarios (por lo tanto, es menos propenso a errores y es más fácil de comprender el código), así como un código más ampliamente aplicable (el diseño anterior sería un desperdicio tanto en el procesamiento como en la eficiencia intelectual humana para arreglos pequeños que nunca necesitan ser ordenados).

Evitar dependencias externas superfluas

Es posible que pueda implementar el código más conciso imaginable con la máxima reutilización de código utilizando 13 bibliotecas diferentes para realizar una tarea relativamente simple. Sin embargo, eso transfiere la sobrecarga intelectual a sus lectores al tener que hacerles entender al menos partes de 13 bibliotecas diferentes. Esta complejidad inherente debe ser apreciada de inmediato por cualquiera que haya intentado construir y comprender una biblioteca de terceros que requirió ingresar y construir una docena de otras bibliotecas para funcionar.

Esta es probablemente una visión muy controvertida, pero preferiría una modesta duplicación de código al extremo opuesto siempre que el resultado final esté bien probado (nada peor que el código defectuoso no probado duplicado muchas veces). Si la opción es entre 3 líneas de código duplicado para calcular un producto vectorial cruzado o extraer una biblioteca matemática épica solo para eliminar 3 líneas de código, sugeriría la primera a menos que todo su equipo esté a bordo con esta biblioteca matemática , en ese momento aún podría considerar escribir 3 líneas de código en lugar de 1 si es lo suficientemente trivial a cambio de los beneficios de desacoplamiento.

La reutilización del código es un acto de equilibrio. Reutilice demasiado y transfiera la complejidad intelectual de una manera de uno a muchos, ya que en esas 3 líneas de código simple que guardó anteriormente tiene el costo de exigir a los lectores y mantenedores que comprendan mucha más información que 3 líneas de código . También hace que su código sea menos estable, ya que si la biblioteca matemática cambia, también podría cambiar su código. Reutilice muy poco y también multiplique la sobrecarga intelectual y su código deja de beneficiarse de las mejoras centrales, por lo que es un acto de equilibrio, pero vale la pena mencionar la idea de que es un acto de equilibrio, ya que tratar de eliminar cada pequeña forma de duplicación modesta puede generar para un resultado que es tan difícil de mantener, si no más, que el extremo opuesto.

Pon a prueba la mierda

Esto es un hecho, pero si su código no maneja todos los casos de entrada y pierde algunos casos extremos, ¿cómo puede esperar que otros mantengan el código que escribió que ni siquiera entendió antes de que se transfiriera a sus ojos y manos? Es bastante difícil hacer cambios en el código que funciona perfectamente, mucho menos código que nunca fue del todo correcto en primer lugar.

Además de eso, el código que pasa pruebas exhaustivas generalmente encontrará menos razones para cambiar. Eso se relaciona con la estabilidad que es aún más un santo grial para lograr que la mantenibilidad, ya que el código estable que nunca necesita ser modificado no conlleva ningún costo de mantenimiento.

Documentación de interfaz

Priorice "qué hacen las cosas" sobre "cómo las hacen" si no puede dedicar el mismo tiempo a documentar ambas. Una interfaz clara que sea obvia en sus intenciones sobre lo que hará (o al menos, lo que se supone que debe hacer) en todos los casos de entrada posibles dará una claridad de contexto a su propia implementación que guiará en la comprensión no solo de cómo usar el código, pero también cómo funciona.

Mientras tanto, el código que carece de estas cualidades donde las personas ni siquiera saben lo que se supone que debe hacer es SOL, sin importar cuán bien documentados estén sus detalles de implementación. Un manual de 20 páginas sobre cómo se implementa el código fuente no tiene ningún valor para las personas que ni siquiera pueden entender exactamente cómo se supone que se debe usar en primer lugar y qué se supone que debe hacer en todos los escenarios posibles.

Para el lado de la implementación, priorice documentar lo que hace de manera diferente a los demás. Como ejemplo, Intel tiene una jerarquía de volumen límite para sus núcleos de trazado de rayos. Como trabajo en este campo, puedo reconocer la mayor parte de lo que hace su código de un vistazo sin examinar la documentación. Sin embargo, hacen algo único, que es la idea de atravesar el BVH y realizar intersecciones en paralelo utilizando paquetes de rayos . Ahí es donde quiero que prioricen su documentación porque esas partes del código son exóticas e inusuales en la mayoría de las implementaciones históricas de BVH.

Legibilidad

Esta parte es muy subjetiva. Realmente no me importa mucho la legibilidad de un tipo cercano a los procesos de pensamiento humano. El código más bien documentado que describe las cosas al más alto nivel aún me resulta difícil de seguir si el autor utiliza procesos de pensamiento extraños y complicados para resolver un problema. Mientras tanto, el código breve que usa nombres de 2 o 3 caracteres a menudo puede ser más fácil de entender para mí si la lógica es muy sencilla. Supongo que podrías hacer una revisión por pares y ver qué prefieren otras personas.

Estoy principalmente interesado en la mantenibilidad y, lo que es más importante, en la estabilidad. El código que no encuentra razones para cambiar es uno que tiene cero costos de mantenimiento.

usuario206767
fuente
1

Diría que una forma de saber sería si los nuevos miembros del equipo pueden recoger el código, comprenderlo y modificarlo para corregir defectos / cumplir nuevos requisitos con relativa facilidad.

FrustratedWithFormsDesigner
fuente
1

Aquí hay una técnica que me gusta usar:

Muestre el código a uno de sus programadores pares y haga que le expliquen lo que hace. Esté atento a estas cosas.

1) Si no pueden explicar fácilmente el propósito de un bloque de código, refactorícelo.
2) Si tienen que saltar a otra sección de código para comprender la sección actual, refactorícela.
4) Cada vez que sientas ganas de hablar durante el proceso, esa sección del código necesita una refactorización. (El código no habla por sí mismo).

JohnFx
fuente
Asumiendo que el programador de pares es al menos igualmente experimentado y leído en el lenguaje de programación y sus expresiones idiomáticas. A menudo, técnicas como estas pueden llevar a las personas a escribir código en un subconjunto de la expresividad del lenguaje en un intento equivocado de hacer que el int sea comprensible incluso para el miembro más joven del equipo. El resultado es un cuerpo de código más grande en un subconjunto tonto del lenguaje. Y no importa cuánto disminuya el subconjunto de idiomas, 500KLOC de código de subconjunto de idioma pequeño siempre será más difícil de mantener que el código de 200KLOC que usa un subconjunto más expresivo.
user1703394
esto parece simplemente repetir lo que se dijo en la respuesta superior
mosquito
-1

El código más fácil de mantener es el código que no está allí. Por lo tanto, en lugar de agregar al recuento de LOC, el nuevo código que 'reduce' el recuento de LOC (incluso si es menos difícil de mantener cuando se ve de forma aislada) podría hacer que la base de código total sea más fácil de mantener simplemente reduciendo su tamaño. Por lo tanto, la regla principal para el código mantenible:

  • maximizar SECO.

En segundo lugar, no hay nada peor para la mantenibilidad que las dependencias ocultas. Entonces, para la regla número 2:

  • Haz explícitas todas tus dependencias.

En tercer lugar, no todos los programadores tienen la misma habilidad para mantener o escribir utilizando técnicas o idiomas específicos más avanzados. Simulando toda la base de código, obtendrá una gran base de código que, debido a su tamaño, es difícil de mantener. Permitir características y modismos de técnicas avanzadas en todo el código hará que todo el código sea mantenible solo por desarrolladores senior, lo que también es malo. La clave para la mantenibilidad es la estratificación basada en el nivel de habilidad. Por ejemplo:

Bibliotecas de proyectos cruzados: desarrolladores senior, código completo de trucos / modismos / técnicas Bibliotecas específicas del proyecto y backend del sistema: desarrolladores intermedios, evite las cosas más avanzadas y difíciles de explicar. Las personas mayores revisarán este código en busca de oportunidades de mejora DRY.

Front-end: desarrolladores junior, use una guía de estilo estricta y un conjunto de técnicas de construcciones de lenguaje y modismos para evitar. Los desarrolladores de Medior revisarán este código en busca de oportunidades DRY y lógica empresarial oculta.

Entonces, para la regla número 3:

  • Coloque su código por nivel de habilidad del desarrollador y escriba el código que se pueda mantener en consecuencia.

yo

usuario1703394
fuente
1
Esto no parece ofrecer nada sustancial sobre los puntos hechos y explicados en las 25 respuestas anteriores
mosquito
@gnat, esperaba agregar 'matices' a muchas simplificaciones excesivas (potencialmente dañinas) en otras respuestas. Especialmente con el punto 3.
user1703394
1
@ user1703394 esta pregunta y sus respuestas son wiki de la comunidad. Si cree que una respuesta existente podría mejorarse, puede editarla incluso sin el privilegio de "editar las publicaciones de otros usuarios".
-2

Nunca es demasiado fácil intentar escribir código legible y fácil de mantener, pero no es difícil escribir un código fácil y fácil de mantener.

OOAD es una palabra de cuatro letras, pero es difícil de entender de una vez: siga el análisis y diseño orientado a objetos

  1. Siempre comience con una buena recopilación de requisitos y la declaración exacta del problema

    • comenzar con pocos casos de uso, es decir; Interacción de diálogo sistema-usuario
  2. Debe mantener sus objetos sueltos y asegurarse de que su código no se repita: siga DRY [No se repita]

    • cada vez que vea un duplicado, busque un lugar para encapsular
  3. su código está abierto para extensión y cerrado para modificación - OCP [principio abierto-cerrado]
  4. Cuando cambie su código, recuerde siempre: no cree problemas para resolverlos, simplemente dice que no modifique su funcionalidad existente
  5. Unidad prueba tu código
    • siempre prueba tu código cuando las cosas salen mal
  6. Mientras trabaje en la funcionalidad, recuerde siempre seguir la OOP básica (principios orientados a objetos) y las técnicas para asegurarse de que su aplicación esté bien diseñada desde el principio
    • Los objetos deben hacer lo que su nombre indique
    • Cada objeto debe representar un concepto único
  7. Recuerde siempre la declaración del problema del sistema y en qué contexto / software de dominio funciona
  8. Haz algo de papeleo también, sí, eso funciona para mí
    • tener algunas impresiones de cosas relacionadas con la interfaz de usuario y diagramas UML siempre funcionan
    • incluso puede obtener las capturas de pantalla de la sesión de lluvia de ideas desde la pizarra
  9. Diseños de arquitectura
  10. Aplicar principios de diseño si es posible
  11. Documentación
    • siempre documente su código
    • establecer sangría en el IDE y documentar eso también
Narender Parmar
fuente
1
Esta es una teoría que no responde a la pregunta ¿Cómo cuantificamos o medimos la calidad del código para que sepamos que es legible, comprensible y mantenible? pregunta
Jan Doggen
De acuerdo !! pero si seguimos los principios mencionados anteriormente, es fácil medir la calidad del código, legible, comprensible y obviamente mantenible. Corrígeme si estoy equivocado.
Narender Parmar
No sé por qué mi respuesta fue rechazada, incluso si ya
cubro