¿Cómo nació este trabajo?

Este trabajo comenzó con algo que mi director notó desde su rol como docente de la FaMAF y su experiencia en la industria: muchos compañeros, colegas y alumnos escriben código complicado, poco claro y difícil de seguir o mantener. Por mi parte, siempre busqué mejorar mi forma de programar, poniendo atención a los nombres que utilizo, al estilo de cada lenguaje y la forma de estructurar las funciones. Y del mismo modo, muchas veces me encontré con códigos que no respetaban esto o que simplemente eran innecesariamente complejos.

De ahí surgió la necesidad de establecer algunas reglas claras y, a la vez, lo suficientemente simples como para no tener que sobrepensar cada línea al programar. Muchas de las bibliografías que ya abordan estos temas suelen volverse demasiado complejas, por lo que no son ideales para quienes recién empiezan, perdiendo así su propósito.

En un principio, este trabajo también buscó servir de base para una materia optativa o un curso breve que enseñe estos principios de una forma más práctica. Como ya se mencionó en la introducción, enseñar a escribir un buen código no es una tarea fácil: faltan recursos y el tiempo disponible muchas veces no alcanza para dar a cada alumno la atención necesaria. Por ahora, esta idea de asignatura está pausada, pero no descartamos ofrecer en el futuro este contenido como una herramienta adicional a quienes están dando sus primeros pasos.

Hoy este trabajo se presenta como un punto de partida, resumiendo criterios y proponiendo formas de escribir y compartir un código bonito. A continuación, retomamos esta idea con algunos aspectos clave que pueden servirnos para validar si estamos frente a un código bonito.

Aspectos para validar un código bonito

Durante los primeros parrafos de este trabajo introdujimos por primera vez el concepto de código bonito: un código es bonito si es claro, prolijo y está bien estructurado, idea que nos acompañó a lo largo de todos los capítulos. Dada que esta definición no es para nada formal y puede tener muchas interpretaciones, nos dedicamos a explicar cómo mejorar en la escritura de este tipo de código mediante los lineamientos.

Entonces, con todos estos lineamientos explicados, nos gustaría complementar respondiendo a la siguiente pregunta:

¿Cómo detecto un código bonito?

El código bonito debería ser identificable a simple vista; sin embargo, como todo, esto se logra con mucha práctica, escribiendo y leyendo una gran cantidad de códigos diferentes. Al final, esta no es una habilidad que se aprenda de la noche a la mañana.

Entonces, nos parece necesario conocer la siguiente lista para no sólo escribir, sino también reconocer código bonito:

1. Al leer funciones, clases y variables, deberíamos ser capaces de entender su propósito con sólo leer su nombre. El tipado y la documentación interna del código deben reforzar esta claridad.
2. Las funciones y métodos deben estar bien organizados, ser cortos y concisos. Sin flujos excesivamente complejos que dificulten la lectura. Además, las sentencias deben respirar, cada momento del código debe estar claramente diferenciado.
3. Debemos encontrar consistencia en el código, no sólo en el idioma, sino también en la forma de escribir y estructurar las sentencias. Un código que sigue las convenciones de su lenguaje en general será bien conciso.
4. No deberíamos encontrarnos con comentarios por todo el código. Estos deben ser pocos y realmente aportar un valor cuando el código no puede ser lo suficientemente expresivo por si mismo.
5. La arquitectura del sistema tiene que mostrar una organización clara, todas las partes deben poseer una responsabilidad bien definida y con límites en su alcance.
6. Por último, debemos encontrar tests en el código de nuestro sistema, organizados por nivel de complejidad e interacción entre componentes. El cuidado en la escritura de las pruebas debe ser el mismo que posee el resto del código.

Con todo esto y junto a los lineamientos desarrollados a lo largo del trabajo, culmina nuestra forma de explicar qué es un código bonito. Es posible que algún desarrollador no esté de acuerdo con algunos de los puntos mencionados -y esto está bien-, al no existir una definición formal, no se puede pretender que todos encontremos el código claro de la misma manera. Pero más allá de la opinión personal, un código que cumple con estas ideas rara vez será difícil de leer y mantener.

¿Qué aprendí y cómo cambió mi forma de escribir código?

Con el pasar de los días mientras realizaba este trabajo, fui notando cómo mi forma de escribir código fue mejorando. Como mencioné al principio, siempre me importó la prolijidad, pero durante el desarrollo de este proyecto pude realmente reforzar hábitos y descubrir prácticas que quizás antes pasaba por algo o no valoraba lo suficiente.

En primer lugar, este proyecto me abrió las puertas a conocer aún más Python, un lenguaje que había usado muy poco porque suelo trabajar con TypeScript.

En cuanto a los lineamientos también aprendí algunas cosas, una de las principales fue la importancia de tener funciones cortas. Con el paso de las semanas comencé a modularizar y repensar más la forma en la que implemento mis funciones. También cambió mi manera de escribir comentarios: hoy escribo muchos menos, sólo los necesarios, sobre todo cuando trabajo en equipo y hay que dejar en claro algunos aspectos importantes. La cantidad bajó en gran manera y la calidad subió.

Si pensamos en las clases, ya conocía el concepto de inyección de dependencias, pero nunca lo había usado de verdad ni tampoco le veía una funcionalidad práctica. Recién cuando me tocó implementarla en un proyecto real entendí su utilidad y el potencial que posee.

Por último, con el testing, sentí algo similar. Nunca realicé muchas pruebas en mi código más allá de lo básico sobre funciones núcleo. Pero ahora tengo más claro cómo debo organizar las pruebas y comprendo en profundidad cómo utilizar los diferentes tipos de tests que existen. Si bien todavía no es parte del día a día en mi trabajo, me siento preparado para hacerlo bien cuando llegue el momento adecuado.

Si alguien me preguntara ¿qué fue lo más difícil de entender?, respondería que las capas en el capítulo de organización de un proyecto de software. Si bien entendía la idea de dividir y ordenar el sistema en diferentes partes con sus responsabilidades claras, escribir esto fue un desafío. Principalmente porque es un tema muy estudiado por muchas personas y no quería ‘reinventar la rueda’ ni mucho menos ir en contra de prácticas ya consolidadas.

¿Cómo cambie a mi entorno?

En cuanto a los cambios que noté a mi alrededor, principalmente en el ámbito laboral, puedo destacar dos cosas. Primero, mis compañeros más cercanos empezaron a mostrar mayor interés en escribir mejor cuando me toca revisar su código. Y segundo, incluso quienes no trabajan directamente conmigo, cada vez que surge algo relacionado con escribir buen código, hacen referencia a este proyecto. Eso me hace creer que realmente se logró dejar una huella.

Recepción del trabajo

Uno de los objetivos al iniciar este trabajo era hacer pública toda la información, de forma accesible y práctica, con la idea en mente de que llegue al mayor número de personas posibles. Para lograrlo, desarrollamos esta página web, donde cada ciertas semanas se publicaba un nuevo capítulo. Aprovechando esto, decidimos incorporar herramientas para medir y analizar el impacto real en los visitantes. A continuación se presentan algunas de las métricas obtenidas:

Usuarios totales

En la figura 1 se observan los usuarios conectados por día, desde el primero de abril de 2025 hasta el 7 de julio de 2025, casi 100 días. En la cabecera de la figura, podemos ver que el total de usuarios activos en el período fue de 731 (los usuarios nuevos corresponden a usuarios que abrieron la página por primera vez, lo ignoraremos en este caso ya que parece hubo algún error de conteo).

Figura 1: Histórico de usuarios activos

Podemos notar tres picos de visitas que sobresalen sobre el resto. El primero pico corresponde a la primer quincena de abril, durante estos días hicimos la primera publicación en redes, principalmente LinkedIn, de la página. Luego, los picos de junio y julio corresponden a las publicaciones de los capítulos de organización de un proyecto de software y testing, ambos también fueron difundidos por redes sociales.

En la cabecera también podemos observar el tiempo medio de interacción de los usuarios activos, pero esta métrica también la ignoraremos ya que considera los días donde no hubo mucho tráfico. Reduciendo así el tiempo en la página.

Encuestas por capítulo

Además de la cantidad de usuarios, nos interesamos por la recepción, opinión y perfil de los mismos. Es por ello que cada capítulo incluía una breve encuesta de dos preguntas y un campo de texto opcional para comentarios adicionales. Las preguntas eran:

• ¿Qué opinas sobre el contenido del capítulo X?
• ¿Cuál es tu perfil?

A continuación observaremos los resultados obtenidos:

Introducción

Figura 2: Opinión del capítulo/cantidad de perfiles en el capítulo Introducción

En la figura 2 observamos 9 respuestas: 5 lectores afirmaron que aprendieron cosas nuevas, mientras que los 4 restantes indicaron que reforzaron los conocimientos. Cabe destcar que, salvo una excepción, quienes eligieron la primera opción son entusiastas autodidactas o estudiantes nuevos en carreras relacionadas a la programación, lo que muestra cómo los lectores con menos experiencia pudieron aprovechar mejor el contenido del capítulo. En contraste con esto, quienes indicaron que reforzaron sus conocimientos son estudiantes avanzados y desarrolladores senior.

Queremos destacar un comentario de un usuario:

«Entiendo que esté narrado diferente a Clean Code [...], pero no terminé de entender la propuesta de valor [...] ¿Qué conocimiento nuevo aporta para alguien que ya leyó el libro? [...].»

A esto respondemos que Lineamientos para escribir código bonito no es ni una crítica ni una reversión o reinvención de la bibliografía ya existente. Por el contrario, este trabajo se nutre de libros que ya exploran esta problemática. Nuestro objetivo es simplificar y hacer accesible este conocimiento a todos, con ejemplos claros y directos. Muchas veces la bibliografía sobre el tema se aleja de su propósito principal y profundiza en temas más complejos que muchos lectores quizás no buscan en un primer acercamiento.

Sintaxis y semántica

Figura 3: Opinión del capítulo/cantidad de perfiles en el capítulo Sintaxis y semántica

Este es el capítulo donde encontramos mayor cantidad de respuestas, con 14. En la figura 3 observamos que más de la mitad de los lectores reforzaron sus conocimientos, mientras que 5, aprendieron cosas nuevas. En este caso, la distribución es más variada y no sigue ningún patrón destacable, simplemente podemos decir que de algún modo el contenido del capítulo fue útil para todos.

Lo que si nos parece importante destacar, es la presencia de un lector estudiante avanzado de Licenciatura en Física. Esto es de suma importancia para nosotros, ya que nuestros lectores no son sólo estudiantes de programación. Llegar a otras áreas siempre es algo destacable.

Diseño de funciones

Figura 4: Opinión del capítulo/cantidad de perfiles en el capítulo Diseño de funciones

Al igual que en el capítulo anterior, en la figura 4, no encontramos ningún patrón sobre los perfiles de las respuestas. Solamente, al igual que en el capítulo de introducción, hubo 5 lectores que aprendieron cosas nuevas, contra 4 que reforzaron sus conocimientos. Además, nuevamente, contamos un estudiante de Física y un dueño de kiosco que programa por pasión.

En este caso un lector dejó un comentario mostrando su aprobación sobre el capítulo: «[...] Me sentí identificado con la importancia de escribir funciones pequeñas y con una sola responsabilidad, eso lo aplico cada vez que puedo. Me pareció útil también todo lo relacionado con el manejo de indentación y espacios en blanco, que muchas veces se subestima.».

Otro comentario, habló de la función isValidUser: «[...] recomendaría analizar si tantos condicionales son necesarios sólo para un log y no convendría simplificarla a un si/no [...].»

Estamos totalmente de acuerdo con esta observación y queremos aclarar que la función, al igual que muchos otros fragmentos de código presentes en el trabajo tienen un propósito exclusivamente didáctico. No pretenden ser una implementación lista para producción o del día a día.

Documentación y comentarios

Figura 5: Opinión del capítulo/cantidad de perfiles en el capítulo Documentación y Comentarios

En este capítulo nos encontramos con 6 respuestas. En la figura 5 podemos observar que dos estudiantes nuevos en carreras relacionadas a la programación señalaron que aprendieron cosas nuevas, mientras que el resto de lectores, profesionales de la industria y estudiante de Física, reforzaron sus conocimientos. Al igual que en el primer capítulo, el contenido le fue útil a los lectores con menos experiencia. Creemos que esta estadística es importante, dado que en las carreras de programación no se suele enseñar a documentar/comentar, estos temas simplemente se explican como una cualidad que poseen los lenguajes de programación, y que luego el estudiante desarrollará en la práctica.

Organización de un proyecto de software

Figura 6: Opinión del capítulo/cantidad de perfiles en el capítulo Organización de un proyecto de software

En organización de un proyecto de software participaron 7 lectores en la encuesta. En la figura 6 se observa que 3 de ellos, estudiantes nuevos o entusiastas, indicaron que aprendieron cosas nuevas. Por otro lado, resulta interesante que un estudiante principiante afirmara que reforzó conocimientos que ya tenía. Sin embargo, no es extraño pensar que un desarrollador experimentado ingresó en alguna carrera relacionada a la programación. Para complementar el análisis, los demás perfiles que reforzaron sus conocimientos corresponden a estudiantes avanzados y profesionales con algunos años de experiencia.

Este capítulo tiene mucho contenido y hay mucho de lo que no se habló, ya sea por prioridades o alcance del trabajo. De todas maneras queremos remarcar el siguiente comentario de un lector:

«[...] este capítulo debería mencionar las siguientes particularidades sobre organización de código: [...] el lenguaje, frameworks y/o herramientas utilizadas tiene un impacto muy grande sobre cómo se estructura el código [...]. Se debería aclarar que la utilización de layer_X_Y en el código [...] -a mi entender- no es algo que debería ser copiado.»

En primer lugar, estamos de acuerdo con que la estructura de un proyecto depende en gran medida del lenguaje y framework utilizado, es por ello que procuramos hacer el capítulo lo más genérico posible. Por ejemplo, en la capa 0 nos encontramos con la definición de datos, un concepto que puede tener muchas interpretaciones: una base de datos para un backend, un archivo con los tipos de datos de las respuestas que recibe un frontend, entre otros casos.

Por otro lado, consideramos que hacer uso de layer_X_Y, es algo totalmente subjetivo a cada desarrollador. Algunos encontraran útil hacer una diferenciación de carpetas y capas, mientras que otros preferirán no hacer esto tan explícito. Al final, lo que buscamos con este enfoque de organización por carpetas es hacer que el código sea lo más evidente y comprensible posible.

Testing

Figura 7: Opinión del capítulo/cantidad de perfiles en el capítulo Testing

Por último, tenemos el capítulo sobre testing, los tiempos de este capítulo fueron muy inferior al resto, de todos modos consiguió juntar 6 respuestas. En la figura 7 observamos que el 100\% de los lectores afirmo que aprendió cosas nuevas, dato que no es menor, pues nos hace pensar que no todos los desarrolladores realizan pruebas a su código. En este caso, los perfiles son diversos: estudiantes, profesionales y autodidactas o aprendices.

En este capítulo no encontramos ningún comentario sobre el cual podamos hacer algún tipo de devolución.

Como último dato significativo, nos gustaría remarcar que en ninguna de las 6 encuestas, nos encontramos con una respuesta que contenga la tercera opción: No me aportó nuevo conocimiento, en la pregunta ¿Qué opinas sobre el contenido del capítulo X?. Con esto, podemos asegurar que el público que pudimos medir, se llevó algún aprendizaje en mayor o menor medida.

Para cerrar esta sección, si bien no se trata de una métrica directa de la página o de una respuesta cuantificable, podemos afirmar que el proyecto recibió una gran aceptación por parte de grupos muy diversos en el mundo de la computación: docentes, estudiantes, profesionales con y sin formación universitaria, entre otros.

Con todos estos datos, puedo concluir que se logró el objetivo de poner esta información a disposición de todos los interesados. De todos modos esto no concluye aquí, la página seguirá abierta y las encuestas también. Por lo que seguiremos recopilando información.

Próximos pasos

Antes de dar el cierre, me gustaría comentar que este trabajo será presentado en un evento llamado BeerJS, un espacio donde desarrolladores de JavaScript y TypeScript se reúnen mensualmente a escuchar charlas y pasar un buen momento en un entorno relajado. Esta presentación se realizará el 31 de julio de 2025 e incluirá una charla breve, donde resumiré los principales lineamientos y temas del proyecto. El principal objetivo del evento es que más personas conozcan el concepto de código bonito y se animen a profundizar en él a través de la página.

Además, seguimos en la búsqueda de que algunas materias de nuestra facultad, y por que no de otras, puedan utilizar este material como herramienta complementaria al momento de desarrollar proyectos.

Reflexión final

A simple vista, escribir código bonito puede parecer una tarea sencilla: basta con estar atento a los momentos en que el código se vuelve confuso y buscar alternativas más claras, como muchas de las que se presentaron en este trabajo. Sin embargo, dominarlo de verdad y sostenerlo en el tiempo es la parte difícil. Nadie empieza a escribir código prolijo y de forma automática de un día para otro, esto requiere mucho tiempo, práctica, atención, interiorizar conceptos y, sobre todo, ganas de mejorar.

Aún así, creo que el simple hecho de conocer las ideas y tenerlas en mente ya nos ayuda a programar con conciencia. Es muy probable que, tarde o temprano, alguien -quizás nosotros mismos- deba leer, entender y mantener el código que escribimos. Darle (o darnos) una mano escribiendo de forma prolija es algo que siempre se agradece, y en parte es una forma de empatizar con el resto de desarrolladores. Si retomamos algunas de las analogías mencionadas en los primeros capítulos, donde comparábamos albañilería y programación o el código con una novela literaria, nadie agradecería trabajar con un albañil que no coloca bien los ladrillos, así como nadie disfrutaría de leer una novela llena de errores ortográficos.

Espero que este trabajo sirva como una herramienta útil, no sólo para aquellos que están comenzando a programar, sino también para los que ya tienen algunos años de experiencia y aún así eligen seguir mejorando día a día. Y, sobre todo, que sirva de recordatorio que aunque escribir código bonito sea una tarea difícil de dominar, siempre es posible avanzar de a poco, una línea a la vez.