Comentarios
Para el desarrollo de aplicaciones es importante mantener un estándar y una línea de manejo bien definida, a fin de prevenir los problemas más comunes que enfrenta no solo el desarrollador sino la empresa.
La importancia de realizar esta actividad en el desarrollo de aplicaciones es muy bien expresada así:
“Documentar el código de un programa es añadir suficiente información como para explicar lo que hace, punto por punto, de forma que no sólo los ordenadores sepan qué hacer, sino que además los humanos entiendan qué están haciendo y por qué.
Porque entre lo que tiene que hacer un programa y cómo lo hace hay una distancia impresionante: todas las horas que el programador ha dedicado a buscar una solución y escribirla en el lenguaje que corresponda para que el ordenador la ejecute ciegamente.
Documentar un programa no es sólo un acto de buen hacer del programador por aquello de dejar la obra finalizada. Es además una necesidad que sólo se aprecia en su debida magnitud cuando hay errores que reparar o hay que extender el programa con nuevas capacidades o adaptarlo a un nuevo escenario. Hay dos reglas que no se deben olvidar nunca:
Todos los programas tienen errores y descubrirlos sólo es cuestión de tiempo y de que el programa tenga éxito y se utilice frecuentemente
Todos los programas sufren modificaciones a lo largo de su vida, al menos todos aquellos que tienen éxito
Por una u otra razón, todo programa que tenga éxito será modificado en el futuro, bien por el programador original, bien por otro programador que le sustituya. Pensando en esta revisión de código es por lo que es importante que el programa se entienda: para poder repararlo y modificarlo.”
Los bloques de comentarios se denominan DocBlock y se suelen incluir obligatoriamente antes de namespace, require{_once}, include{_once}, class, interface, trait, function (incluido methods), property, constant y variables (locales y globales).
Existen dos tipos de comentarios: los comentarios de aclaración del código y los comentarios de documentación.
Comentarios de aclaración del código
Este tipo de comentarios se escribe en el medio del código para aclarar su funcionamiento. El comentario en cuestión se debe hacer en la línea inmediatamente superior a la línea de código fuente que se desea aclarar y se deben utilizar los comentarios de doble barra (//) de la siguiente forma:
// se comprueba por si la instancia es null if($instancia === null) { $error = "La instancia es NULL.; }
En caso de que la aclaración sea los suficientemente corta, se puede incluir en la misma línea de código. El punto y coma debe estar separado dos espacios de la primera barra invertida y el texto del comentario debe estar separado un espacio de la segunda barra:
$i++; // incrementamos la variable
En caso de que el comentario aclaratorio sea bastante largo, se deben usar los comentarios multilínea con apertura (/*) y cierre (*/). El uso de asteriscos en cada inicio de línea es opcional aunque recomendable teniendo en
cuenta que muchos editores los añaden automáticamente:
/* * Este es un comentario multilínea para aclarar el * funcionamiento de una o varias líneas de código que * son difíciles de entender por la complejidad del * tratamiento de los datos. */ foreach($datos as $indice => $dato) { if(validarDato($dato)) { enviarDato($indice,$dato); } }
El nivel de indentación de los comentarios debe ser el mismo que el de la línea que comentan y no debería haber ninguna línea adicional entre la última línea del comentario y la línea de código fuente que comentan. Además, entre los asteriscos y el texto debe haber un espacio.
Comentarios de documentación
Los comentarios de documentación son comentarios multilínea con un formato especial y con palabras clave interpretadas por el generador de la documentación.
Estos comentarios se utilizan para la generación de la documentación del API del código fuente, tanto pública (hacia otros programadores) como privada (hacia los programadores de la aplicación).
Los comentarios de documentación comienzan por la apertura de un comentario multilínea seguido de un asterisco. Cada nueva línea del comentario debe ser precedida por un asterisco y su indentación debe ser la misma que el primer asterisco (no la barra oblícua) de la línea de apertura del comentario. El final de la línea debe estar indentada a la misma altura que las líneas intermedias.
Este tipo de comentario es igual que el comentario multilínea mencionado anteriormente añadiéndo un asterisco a la primera línea:
/** * Comentario de documentación de clases y funciones. * * Estos comentarios pueden llevar etiquetas especiales * con significado dentro de la documentación general: * * @author Diego Lago <beosman@gmail.com> * @version 0.2 2008-09-02 */
Los comentarios de documentación deben comentar las clases, los métodos y las funciones. Además, es recomendable comentar las variables de las clases.
Dentro de los comentarios de documentación, como se ha podido comprobar en el ejemplo anterior, pueden (y deben) existir etiquetas especiales que son interpretadas por el generador de documentación. Todas estas etiquetas comienzan por @ (arroba) y pueden ser las siguientes:
@author: Indica el autor de la clase, función, etc.@copyright: Indica la información del copyright de un archivo o clase.@deprecated: Indica que un elemento es antiguo y no se debe usar.@example: Indica un archivo de ejemplo.@global: Documenta una variable global o su uso.@internal: Indica que es documentación interna.@license: Indica la licencia del archivo o clase.@link: Indica un enlace a otro elemento de documentación.@method: Indica la implementación de un método “mágico” de la clase (PHP).@param: En una función indica el tipo de parámetro y sus posibles valores.@property: Indica la implementación de una propiedad “mágica” de una clase (PHP).@return: En una función indica el tipo de retorno de una función y sus posibles valores.@see: Indica que se debe ver además otro elemento de la documentación.@since: Indica desde qué versión está disponible este elemento.@throws: En una función indica el tipo de excepciones que puede lanzar.@todo: Indica cambios futuros en el código.@var: Documenta una variable de una clase.@version: Indica la versión de la clase, archivo o función.
Cada una de estas etiquetas tiene una sintaxis específica por lo que se debe examinar la documentación del generador de documentación para ver su sintaxis específica.
Esta documentación, en caso de generarla, se genera en HTML por lo que se pueden incluir (y es recomendable) etiquetas HTML dentro de la propia documentación.
Importante
Hay que añadir explicaciones a todo lo que no es evidente. No hay que repetir lo que se hace, sino explicar por qué se hace.
Y eso se traduce en:
¿de qué se encarga una clase? ¿un paquete?
¿qué hace un método?
¿cuál es el uso esperado de un método?
¿para qué se usa una variable?
¿cuál es el uso esperado de una variable?
¿qué algoritmo estamos usando? ¿de dónde lo hemos sacado?
¿qué limitaciones tiene el algoritmo? ¿… la implementación?
¿qué se debería mejorar … si hubiera tiempo?