El código fuente como medio de comunicación

codigo-fuente

codigo-fuente

Ya que con lo que más estamos en el día a día es con nuestro código fuente, ¿qué podemos hacer para mejorar la comunicación con él?

Escribir código fuente es como escribir un libro entre varios, así que lo primero que tenemos que haces es acordar una línea editorial, una guía de estilo que describa cómo nombrar las variables, las clases y demás.

También es necesario que tengamos una estructura para ese código fuente (igual que cuando se divide un libro en secciones o capítulos), empezando por la organización en carpetas y módulos que tendrá el proyecto.

Además, esta organización debería ser la misma en todos los proyectos que usen esa tecnología concreta, de tal manera que sea más fácil que un programador se pueda mover de un proyecto a otro con impacto mínimo.

Está claro que también necesitaremos que haya un acuerdo en cuanto a las librerías que vamos a utilizar (sean comerciales, open source o desarrolladas en otros proyectos internos), así como servidores de aplicaciones, bases de datos, ORM, etc. Y estos acuerdos tienen que estar en ese sitio donde compartimos los documentos de los proyectos, en una carpeta fácilmente identificable.

Y con todo esto, ya tendríamos las bases para que a la hora de escribir código, todos vayamos a hacerlo de manera similar. Y para que sea lo más fácil posible coger código de otra persona, necesitamos que este conjunto de letras y números sea auto explicativo en la medida de lo posible.

Eso implica:

Comentar en el código las clases y los métodos, con los parámetros de entrada y salida correspondientes. La mayoría de entornos de desarrollo permiten hacerlo de manera sencilla: por ejemplo, en Visual Studio 2010 basta introducir /// para que aparezca la plantilla del comentario para el método.

Además, cuando haya un fragmento de código particularmente complejo, deberíamos aclarar por qué está así implementado.

También es útil marcar las cosas que se han dejado pendientes de alguna manera especial (la etiqueta TODO está bastante extendido).

Puede ser porque se esté esperando a que se implemente otra parte, porque hayamos metido algo temporal (por ejemplo, haciendo un mockup de un método para que otras partes del código puedan llamarlo, iríamos remplazando los TODO por la implementación real), etc.

Evidentemente, el código no puede explicarlo todo y de ahí que necesitemos también diagramas de arquitectura y de flujos para explicar cómo interactúan las diferentes partes del código entre sí.

Bien, ¿qué más podemos hacer con el código para mejorar la comunicación?

Pues que cuando lo subamos al control de versiones, todo el mundo sepa por qué lo hemos subido: ha sido para arreglar el bug AAA, para mejorar la documentación, para implementar la funcionalidad XXX correspondiente a la tarea YYY del Sprint, hemos hecho un refactor del módulo ZZZ, etc.

Esto podría facilitar el tener un changelog entre versión y versión del producto, el aviso de pasar pruebas de regresión al módulo objeto del refactor por parte del grupo de QA, etc.

Un caso de éxito de comunicación en este sentido es la manera en que funciona GitHub, que anima a los programadores a compartir sus comentarios sobre el código de los demás, haciendo de la programación algo realmente social.