Documentar el código
Documentacion March 8th, 2008
Cuando uno pasa de hacer pequeños programillas o pequeños sitios web, que no contienen más que 10 o 20 archivos, a desarrollar programas que contienen cientos de archivos y miles de líneas de código se plantea un problema: comentar el código.
Para solucionarlo hay varias herramientas que facilitan enormemente este trabajo, y nos permiten disponer de una buena documentación técnica. El más usado en PHP es el PHPdocumetor, una buena aplicación desarrollada en PHP que crea facilmente una completa documentación permiendo exportarla al formato que necesitemos: HTML, PDF o CHM.
A pesar de que PHPdocumentor es muy popular, yo también al utilizo, hay otras herramientas para generar documentación en PHP: PHPDoc (parezca lo que parezca por su nombre no es la misma aplicación, aunque ambos están desarrollados en PHP), Doxigen y PHPxRef.
Pero antes de que podamos usar alguna de estas aplicaciones, debemos comentar correctamente nuestro código. Para que reconozca correctamente los comentarios estos deben hacerse del siguiente modo:
/**
* Clase de ejemplo
*
* Descripción de la clase de ejemplo
* Palabras clave especiales para definir documentación
*/