Martin Fowler: "Código como documentación"

Releyendo algunos artículos de Martin Fowler (gurú/pensador relacionado con Análisis & Diseño en POO) caigo en este artículo que, fuera de no ser tan técnico, considero un tema base a tratar en los equipos de desarrollo como así también sobre cómo se podría aumentar la calidad del código de un desarrollador que se considere "profesional".

En lo personal prefiero ser siempre "simple", clarificar lo suficiente el código como para que hasta un novato pueda entenderlo y esto no me hace menos "experto" por hacer código "entendible".

Lo que hay que evitar es la "sobre-ingeniería", es decir, ser complejos por el simple hecho que nuestra mente sea -tal vez- un poco más rápida que el resto, o simplemente, porque llegamos a tal grado de "optimización temprana" que creemos que nuestra calidad es elevada cuando "resumimos" 50 líneas en unas pocas 5.

Nota al margen: tanto "sobre-ingeniería" como "optimización temprana" son dos males detectados en la ingeniería de software y deben evitarse.

Algunos ejemplos de lo histérico que puedo llegar a ser ;-). Tengo la costumbre inconsciente de:
  1. Separar las sentencias relacionadas entre sí como si fueran párrafos de un artículo: veo a muchos desarrolladores que toman un método de una clase y en todo su contenido no hay una sola línea de separación, todo junto, todo "pegado". Lo primero que hago es empezar a separar como párrafos de un artículo: cuando las líneas de código están relacionadas, van juntas ("punto y seguido"), pero cuando las líneas tratan otro tema agrego una línea en blanco ("punto y aparte"). A mi me costaría leer un libro o un artículo que tiene contenido sin separar, ¿por qué no me pasaría eso con el código de un sistema?
  2. Evitar los "elseif" porque anidar condiciones genera un código difícil de seguir, ya que tenemos que estar evaluando cada condición y todos sus caminos alternos. Si no quedara otra simplificación, trato de cambiar el elseif por un simple else y coloco dentro un "if" aparte y agregarles lineas de separación. En parte está relacionado con el punto anterior (no mejora la lógica pero sí su lectura y entendimiento).
  3. Inmediatamente eliminar cualquier "número mágico", técnica de refactoring que dice algo así como "sustituir todos los códigos numéricos que hay por todo nuestro sistema y cambiarlo por una constante que lo describa", lo cual ya evita que tengamos que hacer un comentario antes del "número mágico".
  4. Cambiar los nombres de variables y hacerlas más descriptivas, sin importar lo largas que me queden: si el caso es muy obvio, no tengo problemas de agregar una variables del tipo "ret" o "retorno", pero en el caso donde lo obvio es peligroso, o donde no es tan obvio, trato que las variables sean tan descriptivas que no haga falta agregar un comentario para explicar para qué sirven, y el lugar más indicado es con los parámetros de un método.
  5. Abrir el código en varias líneas hasta que sea entendible: no tengo pudor en ampliar una línea de código en varias hasta que quede claro, aún sabiendo que puedo yo mismo entenderla con una sola línea. Lo importante, otra vez, no es si solo yo lo entiendo, es si el que viene detrás puede hacerlo, y esto es fundamental para trabajar en equipo y que todos seamos productivos.
Tan malo es hacer código que nosotros mismos nos cueste entender dentro de unos meses, como ser los únicos que lo puedan entender. Un código de alta calidad es el código que todos pueden entender, y hay que comprender que en algún momento u otro, vamos a trabajar en equipo con otra persona, y el código, además de ser entendible para nosotros poder trabajar de forma productiva, debe poder ser entendido por los demás.

Experto es quién hace código entendible, y experto es quién entiende la diferencia entre "código de calidad" y el que no lo es.

Y ahí entra la disciplina "refactoring" que busca, sin cambiar de funcionalidad, que el código mejore su calidad.

¿Y tú, haces código entendible para los demás, para ti, o para nadie? ;-)

6 comentarios:

Ubersoldat dijo...

buff! Yo es que he visto cada código... hecho por mi!!! En fin, es algo que con la experiencia se aprende.

Lo más importante es pensar que dentro de 6 meses te dirán: tal cosa no funciona, arreglala. Cuando te metas en tu código a ver cómo demonios lo has hecho funcionar, agradecerás este tipo de cosas.

enrique_place dijo...

Que tal Ubersoldat:

... nos pasa con código de hace unas semanas! ;-)

Hay que acompañar una pequeña wiki con los detalles del desarrollo, un pequeño UML general y alguna captura de una pizarra... y podremos recuperar un poco la memoria de lo que estábamos pensando en esos malditos días que se nos ocurrió ese código del demonio! :-)

PD: ya estuve por tu blog, voy a probar el coloreado de sintaxis para blogger.

Robert dijo...

Es una lástima ver código tan mal escrito, creo que lo peor que puedes llegar a leer es una clase construida como si fuera una función al estilo procedural sobre PHP 5!

Ek' Lamat dijo...

esencial...

ya me suscribo a tu Blog, y suerte!

Javi López dijo...

Cuando he leído lo de que separas las líneas o las agrupas y demás me he sentido plenamente identificado, a fecha de hoy, creo que un desarrollador que no siga esa sería de "normas": camelCase, indentación, tabulación, ... es como si cometiese errores ortográficos en un documento escrito.

Me ha gustado mucho tu artículo.

enrique_place dijo...

Gracias por los comentarios. ;-)

Lo peor que he visto a la fecha es "seudo-programadores" que tienen blogs para decir cual es la mejor forma, qué se debe hacer, copian contenidos de otros lados y suben uno y otro documento pdf con presentaciones de "buenas prácticas"... pero ellos mismos no se reconocen como "malos programadores" y que codifican para "ellos mismos", y en caso que los demás no los entiendan, el problema es por su supuesta "falta de conocimientos" de sus lectores.

No creo ni apoyo a los "programadores gurú" que solo entienden ellos el código.

Si fuera así, el Software Libre tendría los días contados.

Entradas populares