Infraestructura 3: documentando el código
En la buena práctica denominada código limpio sólo son admisibles los comentarios que expliquen la funcionalidad de alguna clase, función o variable, o que añada información a la misma de forma que sea más sencillo trabajar con ella dentro de un IDE, pero también, evidentemente, de forma que sea más fácil de usar por miembros del equipo que no hayan estado involucrados directamente en la creación (o revisión) de la misma.
Por eso la mayoría de los lenguajes de programación contienen, dependiendo del mismo, o una práctica habitual o un estándar que describe como hacer este tipo de comentarios. En general, a estos comentarios se los denomina docstrings, y generalmente contienen
- Una descripción de la funcionalidad.
- Algunas flags con descripción adicional, especialmente si se trata de funciones deprecadas, es decir, que van a desaparecer en versiones posteriores de la aplicación.
- Descripción de los parámetros que se usan y sus tipos.
- Descripción de los errores que se puedan producir al ejecutarle, y las excepciones que se puedan tirar.
- Descripción de los valores de vuelta de la función.
En general, el formato que se use habitualmente en el lenguaje permitirá indicar cada una de estas cosas de una forma determinada; una vez hecho esto, IDEs tales como Code mostrarán, al pasar el cursor sobre una función o al escribir el nombre de la misma, un pop-up que mostrará esta documentación; también comprobará estáticamente los tipos de las variables con las que se invoca algo para que sean correctos; finalmente, autocompletará en algunos casos los valores de las variables. En general, la documentación facilita la vida tanto al resto de los programadores como a los entornos de programación.
Aunque se puede usar esta documentación en línea de forma directa, en general el toolchain del lenguaje incluirá también una forma de generar a partir de ella documentación en algún otro formato publicable, HTML o PDF, generalmente. También conviene integrar esta generación de documentación dentro de los flujos de trabajo del proyecto, de forma que se registre automáticamente.