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? ;-)