CódigoComoDocumentación
Escrito por Martin Fowler
Traducido por Rafael Vacas
Revisado por Jorge Ferrer
Uno de los elementos comunes de los métodos ágiles es que otorgan a la programación un papel central en el desarrollo de software – mucho más de lo que la ingeniería del software suele hacer. Para esto es necesario considerar el código como la principal documentación de un sistema software.
Casi de inmediato siento la necesidad de refutar un malentendido muy común. Tal principio no quiere decir que el código sea la única documentación. Aunque a menudo se dice esto de la ProgramacionExtrema, nunca lo he oído decir a los líderes de éste movimiento. Generalmente, se necesita documentación adicional como complemento al código.
La razón por la que el código es la fuente principal de documentación se debe a que es la única lo suficientemente detallada y precisa como para ocupar este rol - un punto explicado elocuentemente por Jack W. Reeves en su famoso ensayo "¿Qué es Diseño?".
Este principio tiene una importante consecuencia - la importancia de que los programadores nos cercioremos de que el código sea claro y legible. Decir que el código es documentación no quiere decir que cualquier código fuente sea una buena documentación. Como cualquier documentación, el código puede ser un código claro o ser un guirigay. El código no es intrínsecamente más claro que cualquier otra forma de documentación (y otras formas de documentación pueden ser también desesperadamente poco claras), he visto multitud de diagramas UML que no son mas que garabatos sin ninguna utilidad.
Ciertamente parece que la mayoría de los códigos fuente no son muy buenos como documentación. Pero así como es un error concluir que por considerar el código como fuente de documentación se deban excluir otras formas de documentación, también es un error decir que, como el código a menudo es pobre como documentación, tenga que ser necesariamente pobre. Es posible escribir código claro y legible, de hecho estoy convencido de que la mayoría de los fuentes pueden ser mucho más claros.
Pienso que una de las razones por la cual el código es tan difícil de leer es porque la gente no se lo toma en serio como documentación. Si no existe la voluntad de hacer código claro, tampoco existe la menor posibilidad de que el código sea claro por si mismo. Por tanto, el primer paso para hacer código claro es aceptar que el código es documentación y a continuación poner el empeño en hacer código claro. Creo que esto se debe a la forma en que se enseña a los programadores cuando estos empiezan a programar. Mis profesores no pusieron mucho énfasis en hacer código legible, no parecían darle valor y ciertamente no decían como hacerlo. Nosotros, como industria, necesitamos poner mucho más énfasis en dar valor a un código claro.
El siguiente paso es aprender cómo, y aquí permitidme daros el consejo de un autor técnico de éxito en ventas - no hay nada como las revisiones de código. Nunca se me pasaría por la cabeza publicar un libro sin que haya un montón de gente dispuesta a leerlo y darme su opinión. De la misma forma, no hay nada más importante para un código claro que obtener la opinión de otros acerca de si es fácil o no de entender. Por tanto, debes aprovechar cada oportunidad y encontrar la forma de que la gente lea tu código. Descubre lo que encuentran fácil de entender, y lo que les confunde (Sí, programar por parejas es una buena forma de conseguirlo).
Como consejo recomiendo la lectura de buenos libros sobre estilos de programación. Code Complete es un buen punto de partida. Naturalmente recomiendo Refactoring - después de todo, mucho del refactoring tiene que ver con hacer el código mas claro. Después de Refactoring, Refactoring to patterns es una sugerencia obvia.
Siempre encontrareis a gente que discrepe en muchos puntos. Recordad que el código fuente pertenece en primer lugar al equipo (incluso aunque haya pedacitos de código que sientas que te pertenecen a ti en particular). Un programador profesional está preparado para adaptar su estilo personal de forma que se alinee con las necesidades del equipo. Así, aunque tengas predilección por los operadores ternarios, no los uses si tu equipo no los encuentra fáciles de entender.
Puedes programar con tu propio estilo en tus proyectos personales, pero cualquier cosa que hagas en un equipo debe seguir las necesidades del equipo.
Artículo Original
