Como hacer que tu código sea legible

Reconozco que no soy el mejor programador del mundo, pero intento mejorar cada día. Puede sonar tonto, pero una de las mayores complicaciones del trabajo de un programador es conseguir que el código que escribes un día sea entendible por otras personas !y nosotros mismos! en el futuro.

Casi todo lo que voy a contar a continuación lo he aprendido a partir de diversas lecturas y por propia experiencia.

Algunos de los consejos más útiles que creo que son importantes tener en cuenta son:

Utiliza el inglés al programar

Puede resultar extraño para algunos que dominando un idioma (español, portugués, francés, etc.) tengan que programar en inglés. El motivo es sencillo, la mayor parte de la documentación en nuestro sector está en inglés por lo que acabamos mezclando idiomas. ¿A quién no le ha pasado tener funciones llamadas setPeso o getNombre?

Por otra parte, el inglés permite abrirnos puertas en dos sentidos:

  • Para empezar como programadores que dominemos el inglés podremos acceder a más puestos de trabajo. La globalización no es sólo para las empresas; nosotros también podemos aprovecharnos de ella.
  • Podemos contratar programadores extranjeros que no tendrán problemas al leer el código.

Utiliza normas de codificación

Esto en algunas metodologías se llama gestión de configuración del software. También se puede encontrar como convención de codificación (code convention) o guías de estilo. La idea es tener una serie de normas que indica cómo debe ser la nomenclatura de codificación y tabulación para que todo el desarrollo sea consistente. Con esto conseguimos un programa más homogéneo y fácil de entender.

Tampoco es necesario inventarse una propia porque ya existen muchas. A modo de ejemplo:

Elige bien los nombre

La verdad es que el tema de los nombres es uno de los más complejos. Sobre todo para funciones y clases. Por norma los nombres de métodos, funciones, clases, etc. deben ser descriptivos y breves. Por ejemplo, un nombre como ApplicationModelAbstractObjectFactory quizá sea un poco largo, pero parece descriptivo. Igualmente, algo como EntraSola (caso real) es muy breve, pero no dice nada; no es posible determinar realmente su funcionalidad (además, puede inducir a tener pensamientos impuros).

Utiliza comentarios

Este punto es bastante controvertido porque mucho programadores piensan eso de “el código bien escrito se entiende solo”. Y es verdad. El problema es cuando el código no hace lo que toca.

No hay que llenar el código de comentarios, deben ser lo mínimo posible y sólo para cosas que claramente lo necesiten. Esto suele ser para aquellas construcciones que sean muy abstractas y que cueste mas comprender.

Se organizado

Otro punto que quizá no sea obvio, pero es cierto que tener bien organizado el código ayuda mucho a su legibilidad. Es más fácil entender una función que está dividida en partes (preparación de datos, realización de acciones, generación de resultado) que otra en la que se vayan mezclando todas estas tareas.

Refactoriza

Por mucho que nos esforcemos en que nuestro código sea claro y legible, con el tiempo acabará por convertirse todo en algo caótico. Es normal, porque conforme evoluciona un software se añaden nuevas funcionalidades para las que no estaba inicialmente pensado.

Para evitar esto hay que hacer ciclos de refactorización que mantengan el código limpio y optimizado.

Conclusiones

Está claro que una parte importante para evitar la deuda técnica reside en la calidad del código un código más claro facilita el mantenimiento al poder ser entendido fácilmente (ojo, que a parte de esto es necesario un buen diseño del mismo). El uso de unas normas que permitan que éste sea entendible ayudan mucho para evitar este problema.

Finalmente me gustaría comentar que este artículo es meramente introductorio y faltan muchas cosas que contar. Estoy más que seguro que habrá discrepancias con algunas cosas; si es así, te animo a que dejes un comentario.

Bibliografía

La mayor parte de lo que he expuesto aquí procede del libro The Art of Readable Code de O’Relly.

Errata

  • 2017-02-01: Corrijo la parte de la deuda técnica a sugerencia de Fioddor.

2 comentarios en “Como hacer que tu código sea legible

  1. Mis discrepancias:

    1) No conozco ninguna metodología que llame gestión de configuración del software a las normas de codificación.

    2) La mayor parte de la deuda técnica no está en la codificación, sino en los primeros niveles: concepción/visión del producto, requisitos y arquitectura.

    Sugerencia: Si los nombres salen muy largos declara nombres internos. El nombre interno describe el rol de la variable en el contexto local:

    timador = elHijoDeLaFruteraDeMiCalleCuandoEraNiño
    primo = laSeñoraGordaConElPeloDePuntaQueBarreCada5mins
    gancho = laAmigaDeMiNovia

    De ese modo se desacoplan

    Y finalmente: un abrazo ;-)

  2. Buenas, Fioddor:

    1) Tienes razón, ninguna metodología lo llama así, sino que llaman así a un documento que trae muchas cosas, donde una de ellas puede ser las normas de codificación.

    Según la metodología es más o menos claro lo que debe hacer la gestión de configuración. Por ejemplo, en Métrica v3 no es claro. En cambio, en el estándar de la ESA, en el documento SCMP (Software Configuration Management Plann) es algo más claro:

    All software items, for example documentation, source code, executable code, files, tools, test software and data, shall be subjected to configuration management procedures

    Algunos autores son bastante claros con qué debe hacerse en la gestión de configuración.

    2) La verdad es que me he acostumbrado mucho al rol de Analista/programador y en ocasiones confundo un poco los roles. El caso es que tienes razón y me lo anoto para corregirlo (espero que hoy).

    Me encantan tus nombres internos xD

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *