¿Es necesario que el código generado sea legible por humanos?

https://stackoverflow.com/questions/63257

09-06-2019
|

Pregunta

Estoy trabajando en una herramienta que generará el código fuente para una interfaz y un par de clases que implementen esa interfaz.Mi resultado no es particularmente complicado, por lo que no será difícil hacer que el resultado se ajuste a nuestros estándares normales de formato de código.

Pero esto me hizo pensar:¿Qué tan legible debe ser el código generado automáticamente?¿Cuándo se debe realizar un esfuerzo adicional para garantizar que un ser humano lea y entienda fácilmente el código generado?

En mi caso, las clases que estoy generando son esencialmente contenedores para algunos datos relacionados con otra parte de la compilación con métodos para obtener los datos.Nadie debería necesitar mirar el código de las clases en sí, solo necesitan llamar a los diversos captadores que proporcionan las clases.Por lo tanto, probablemente no sea demasiado importante si el código está "limpio", bien formateado y es fácil de leer para un humano.

Sin embargo, ¿qué sucede si estás generando código que tiene más que una pequeña cantidad de lógica simple?

Solución

Creo que es igualmente importante que el código generado sea legible y siga los estilos de codificación normales.En algún momento, alguien necesitará depurar el código o ver qué está sucediendo "detrás de escena".

Otros consejos

¡Si, absolutamente!;Incluso puedo contarte una historia para que expliques por qué es importante que un humano pueda leer fácilmente el código generado automáticamente...

Una vez tuve la oportunidad de trabajar en un nuevo proyecto.Ahora, una de las primeras cosas que debe hacer cuando comience a escribir código es crear algún tipo de conexión y representación de datos hacia y desde la base de datos.Pero en lugar de simplemente escribir este código a mano, teníamos a alguien que había desarrollado su propio generador de código para crear automáticamente clases base a partir de un esquema de base de datos.Fue realmente genial, el tedioso trabajo de escribir todo este código ahora estaba fuera de nuestras manos...El único problema fue que el código generado estaba lejos de ser legible durante un tiempo. normal humano.

Por supuesto que no lo hicimos, porque bueno, simplemente nos ahorró mucho trabajo.Pero después de un tiempo, las cosas empezaron a ir mal, los datos se leyeron incorrectamente de la entrada del usuario (o eso pensábamos), se produjeron daños dentro de la base de datos mientras estábamos solo lectura.Extraño..porque leer no cambia ningún dato (otra vez, eso pensábamos)...

Como todo buen desarrollador empezamos a cuestionar nuestro propio código, pero después de días de búsqueda...Incluso reescribiendo el código, no pudimos encontrar nada...y luego nos dimos cuenta de que el código generado automáticamente estaba roto.

Así que ahora nos esperaba una tarea aún mayor: verificar el código generado automáticamente que ninguna persona en su sano juicio podría entender en un período de tiempo razonable...Estoy hablando de código sin sangría y con un estilo realmente malo, con nombres de variables y funciones impronunciables...Resultó que sería incluso más rápido reescribir el código nosotros mismos, en lugar de intentar descubrir cómo funciona realmente el código.

Finalmente, el desarrollador que escribió el generador de código lo rehizo más adelante, por lo que ahora produce legible código, en caso de que algo haya salido mal como antes.

Aquí está un enlace que acabo de encontrar sobre el tema en cuestión;En realidad estaba buscando un enlace a uno de los capítulos del libro "programador pragmático" para señalar por qué buscamos primero en nuestro código.

Creo que eso depende de cómo se utilizará el código generado.Si el código no está destinado a ser leído por humanos, es decirse regenera cada vez que algo cambia, no creo que tenga que ser legible.Sin embargo, si está utilizando la generación de código como paso intermedio en la programación "normal", el código generado debería tener la misma legibilidad que el resto de su código fuente.

De hecho, hacer que el código generado sea "ilegible" puede ser una ventaja, porque disuadirá a las personas de "piratear" el código generado y, en su lugar, implementará sus cambios en el generador de código, lo cual es muy útil siempre que necesite regenerar el código. por el motivo que sea y no perder los cambios que hizo su colega porque pensó que el código generado estaba "terminado".

Sí lo hace.En primer lugar, es posible que necesites depurarlo: te lo pondrás más fácil.En segundo lugar, debe cumplir con las convenciones de codificación que utilice en su tienda porque algún día es posible que sea necesario cambiar el código a mano y, por lo tanto, convertirse en código humano.Este escenario generalmente ocurre cuando su herramienta de generación de código no cubre algo específico que necesita y no se considera que valga la pena modificar la herramienta solo para ese propósito.

Buscar generación de código activo vs. generación de código pasivo.Con respecto a la generación pasiva de código, absolutamente si, siempre. Con respecto a la generación de código activo, cuando el código logra el objetivo de ser transparente, que es actuar exactamente como una API documentada, entonces no.

Yo diría que es imperativo que el código sea legible por humanos, a menos que su herramienta de generación de código tenga un depurador excelente, usted (o su desafortunado compañero de trabajo) probablemente estará metido hasta la cintura en el código tratando de rastrear ese error tan esquivo. en el sistema.Mi propia incursión en el 'código de UML' me dejó un sabor amargo en la boca ya que no podía entender el proceso de depuración supuestamente 'elegante'.

El objetivo del código generado es hacer algo "complejo" que sea más fácil de definir en algún lenguaje de nivel superior.Debido a que se genera, el mantenimiento real de este código generado debe estar dentro de la subrutina que genera el código, no del código generado.

Por lo tanto, la legibilidad humana debería tener menor prioridad;cosas como la velocidad del tiempo de ejecución o la funcionalidad son mucho más importantes.Este es particularmente el caso cuando nos fijamos en herramientas como bison y flex, que utilizan el código generado para pregenerar tablas de búsqueda rápida para hacer coincidencias de patrones, lo que sería simplemente una locura mantener manualmente.

Te matarás si tienes que depurar tu propio código generado. No empieces a pensar que no lo harás. Tenga en cuenta que cuando confía en su código para generar código, ya ha introducido dos errores en el sistema: se ha insertado usted mismo dos veces.

No hay absolutamente NINGUNA razón para NO hacerlo analizable por humanos, entonces, ¿por qué querrías hacerlo?

-Adán

Un aspecto más del problema que no se mencionó es que el código generado también debería ser "compatible con el control de versiones" (en la medida de lo posible).

Muchas veces me resultó útil verificar las diferencias entre el código generado y el código fuente.

De esa manera, ocasionalmente podrías encontrar errores en las herramientas que generan código.

Es muy posible que alguien en el futuro quiera revisar y ver qué hace su código.Así que hacerlo algo comprensible es algo bueno.

También es posible que desee incluir en la parte superior de cada archivo generado un comentario que indique cómo y por qué se generó este archivo y cuál es su propósito.

Generalmente, si estás generando código que necesita ser modificado por humanos más adelante, debe ser lo más legible posible por humanos.Sin embargo, incluso si es un código que se generará y nunca se volverá a tocar, aún debe ser lo suficientemente legible como para que usted (como desarrollador que escribe el generador de código) pueda depurar el generador; si su generador genera código incorrecto, puede ser difícil. rastrear si es difícil de entender.

Creo que vale la pena tomarse más tiempo para hacerlo legible por humanos solo para que sea más fácil de depurar.

El código generado debe ser legible (el formato, etc., generalmente puede manejarse mediante un IDE medio decente).En algún momento de la vida del código, alguien lo verá y querrá darle sentido.

Creo que para contenedores de datos u objetos con un funcionamiento muy sencillo, la legibilidad humana no es muy importante.

Sin embargo, tan pronto como un desarrollador tenga que leer el código para comprender cómo sucede algo, debe ser legible.¿Qué pasa si la lógica tiene un error?¿Cómo podrá alguien descubrirlo si nadie es capaz de leer y comprender el código?Yo iría tan lejos como para generar comentarios para las secciones lógicas más complicadas, para expresar la intención, de modo que sea más fácil determinar si realmente hay un error.

La lógica siempre debe ser legible.Si alguien más va a leer el código, intente ponerse en su lugar y vea si comprendería completamente el código en un nivel alto (¿y bajo?) sin leer ese fragmento de código en particular.

No dedicaría demasiado tiempo a un código que nunca se leería, pero si no es demasiado tiempo, revisaría el código generado.Si no, al menos haga un comentario para cubrir la pérdida de legibilidad.

Si es probable que este código se depure, entonces debería considerar seriamente generarlo en un formato legible por humanos.

Existen diferentes tipos de código generado, pero los tipos más sencillos serían:

Código generado que no debe ser visto por el desarrollador.por ejemplo, código xml-ish que define diseños (piense en archivos .frm o los horribles archivos generados por SSIS)
Código generado que está destinado a ser la base para una clase que luego será personalizada por su desarrollador; por ejemplo, el código se genera para reducir el tedio de escribir.

Si estás haciendo lo último, definitivamente Quiere que su código sea legible por humanos.

Las clases e interfaces, sin importar qué tan "fuera del alcance" de los desarrolladores crea que deberían estar, casi con certeza se incluirían en el tipo de código generado número 2.El depurador los afectará en un momento u otro: aplicar formato de código es lo mínimo que puede hacer para facilitar el proceso de depuración cuando el compilador llega a esas clases generadas.

Como prácticamente todos los demás aquí, digo que sea legible.No cuesta nada extra en su proceso de generación y usted (o su sucesor) lo agradecerán cuando vayan a excavar.

Para ver un ejemplo del mundo real, observe todo lo que genera Visual Studio.Bien formateado, con comentarios y todo.

El código generado es código, y no hay ninguna razón por la que el código no sea legible y esté bien formateado.Esto es económico, especialmente en el código generado:No es necesario que apliques el formato tú mismo, ¡el generador lo hace por ti siempre!:)

Como opción secundaria en caso de que seas tan vago, ¿qué tal si canalizas el código a través de una utilidad embellecedora de tu elección antes de escribirlo en el disco para garantizar al menos cierto nivel de coherencia?Sin embargo, casi todos los buenos programadores que conozco formatean su código de forma bastante pedante y hay una buena razón para ello:no hay código de solo escritura.

Absolutamente sí, por muchas buenas razones ya mencionadas anteriormente.Y una más es que si su código necesita ser revisado por un asesor (por cuestiones de seguridad y confiabilidad), es bastante mejor si el código es reescribible por humanos.De lo contrario, el evaluador se negará a evaluarlo y su proyecto será refeado por las autoridades.La única solución entonces es evaluar...el generador de código (que suele ser mucho más difícil;))

Depende de si el código será leído únicamente por un compilador o también por un humano.Además, importa si el código debe ser súper rápido o si la legibilidad es importante.En caso de duda, haga un esfuerzo adicional para generar código legible.

Creo que la respuesta es:Eso depende.

*Depende de si necesitas configurar y almacenar el código generado como un artefacto.Por ejemplo, la gente rara vez guarda o configura la salida del código objeto de un compilador de C, porque saben que pueden reproducirlo desde la fuente en todo momento.Creo que puede haber una analogía similar aquí.*Depende de si necesita certificar el código según algún estándar, p.Misra-C o DO178.*Depende de si la fuente se generará a través de su herramienta cada vez que se compila el código, o si se almacenará para incluirla en una compilación más adelante.

Personalmente, si todo lo que quieres hacer es compilar el código, compilarlo en un ejecutable y luego desechar el código intermedio, entonces no veo ningún sentido en hacerlo demasiado bonito.

Licenciado bajo: CC-BY-SA con atribución

No afiliado a StackOverflow