En esta nueva edición (III) de las pautas y convenciones para CodeQA vamos a hablar sobre otro aspecto importante para asegurar la calidad de nuestro código: su documentación.

En cualquier proyecto IT encontramos todo tipo de documentación asociada, como puede ser una guía de usuario, unas especificaciones técnicas o de rendimiento, e incluso un informe de los resultados obtenidos de las pruebas ejecutadas. Pero, también es importante que el código fuente del proyecto esté debidamente documentado para facilitar su futuro desarrollo y mantenimiento, y en caso de tener API, facilitar su uso por otros desarrolladores.

En este artículo definiremos cómo y cuándo redactar documentación en código según su forma: en comentarios o en documentación API del lenguaje.

Comentarios

Los comentarios son una herramienta presente en cualquier lenguaje de programación que tiene dos funciones básicas. La primera, permite a los desarrolladores inhabilitar una línea o bloque de código para que éste sea ignorado por el entorno de ejecución o intérprete del lenguaje. Esto es muy útil durante el desarrollo ya que permite probar si distintos bloques de código son funcionales, o encontrar qué trozo de código podría haber estado causando un estado no deseado después de su inhabilitación. Aun así, no es recomendable para CodeQA dejar código ejecutable comentado sin ninguna anotación por largo tiempo en el ciclo de vida del software, ya que puede confundir a otros compañeros desarrolladores. Por otro lado, la segunda función de los comentarios es justamente, como indica su nombre, comentar código con el fin de documentarlo, en lo que nos centraremos a continuación.

La documentación de código mediante comentarios se suele reducir a anotaciones breves para clarificar la función o lógica de una o varias líneas de código en concreto. En cuanto al registro que debe usarse en su redacción, puede ser técnico ya que será leído por desarrolladores, pero también debe ser lo más claro y explícito posible. La finalidad de un buen comentario es que aclare un código que pueda ser confuso, ya sea hablando en primera persona plural, como una decisión tomada por el equipo de desarrollo, o en impersonal, en términos de lo que hace el código. Detallaremos ambas formas de redacción en los comentarios del ejemplo de más abajo.

Lo que recomendamos desde SogetiLabs es colocar estas anotaciones justo encima de la línea o bloque a comentar. En casos especiales, se puede colocar una anotación breve al final de una línea para comentar algo especifico, aunque esto no es recomendable porque puede pasar desapercibido si la línea de código es larga.

A continuación, mostramos un ejemplo de ambas situaciones:

Otra forma de documentar el código además de redactar anotaciones también puede ser estructurarlo por bloques según su lógica en un mismo fichero muy extenso. Para hacerlo, podemos escribir en una línea vacía un comentario que ocupe el ancho de línea entero (unos 80 caracteres) con caracteres separadores y un título indicandode qué trata el bloque de código que le sigue.

Como ya hemos dicho antes, los comentarios están presentes en todos los lenguajes de programación, por lo que los caracteres especiales para redactarlos son específicos para cada uno. Por este motivo, los ejemplos que hemos mostrado se han escrito sólo en algunas de las sintaxis más comunes.

Documentación API

La documentación API es un tipo de comentarios en bloque que contiene directivas o palabras clave específicas para definir los inputs/outputs, versión y obsolescencia, autor o referencias de una función, método o clase. Este tipo de documentación es nativa en algunos lenguajes como Javadoc en Java, que incluso interpreta HTML, aunque hay multitud de paquetes que permiten definir y generarla en aquellos que no la tienen nativa. Desde SogetiLabs Spain recomendamos el uso de Swagger como herramienta estándar para la documentación API.

A continuación, distinguiremos entre la documentación API de método o funciones de la de clases, scripts o ficheros.

• En el caso de métodos y funciones recomendamos redactar únicamente su función o finalidad, sin entrar en su lógica interna. Luego, dejando una línea de separación, debemos especificar los parámetros de entrada y el retorno (si lo tiene) junto con su tipo de datos y una breve descripción de una línea al lado, si se considera necesaria. Veamos un ejemplo con un método sencillo que valida una contraseña:

Aun así, podemos omitir documentar métodos o funciones cuyo código sea claramente autoexplicativo o su única función sea acceder o modificar variables. Un ejemplo de esto podría ser los getters o setters (también llamados “accesores”), o funciones sin lógica propia que realicen operaciones intermedias de conversión o formateo de datos como parte de un proceso más complejo.

• Sobre la documentación a nivel de clases, scripts o ficheros,creemos que debe ser obligada para librerías o frameworks, ya que es importante conocer la estructura general de sus componentes y la relación entre ellos. Por ello, se debe redactar una explicación y su autoría, por si es necesario contactar con el creador. En otro tipo de aplicaciones recomendamos como mínimo documentar aquellas partes de código relevantes o críticas, como grandes funciones o las clases principales de la aplicación. El ejemplo siguiente muestra una clase obsoleta que forma parte de una librería:

En esta tercera edición de pautas y convenciones para CodeQA hemos contado las mejores prácticas para documentar directamente el código fuente de nuestros proyectos IT. Con ello, a través de los comentarios, los desarrolladores pueden entender código complejo o escrito por otros compañeros para asegurar el futuro desarrollo y mantenimiento del proyecto. Y, por otro lado, hemos visto como también resulta muy útil para que otros equipos de desarrollo lo entiendan y usen correctamente mediante la documentación API.

En el siguiente artículo trataremos otro tema fundamental sobre CodeQA, la estructuración del código mediante el correcto espaciado, tabulación y saltos de línea en las diferentes estructuras y operadores en el código. Como siempre, estáis invitados a dejar vuestras opiniones. ¡Os esperamos en la próxima!