Así que buscando en Google, caí rápidamente en dos proyectos, creados en PHP, para generar documentación en base al código. Uno llamado PHPDocumentor y el otro PHPDoc (el que diga que los programadores no tienen imaginación a la hora de poner nombres, que sepa que se equivoca). El primero, parece que se erigió como el standar en la generación de documentación, mientras que el segundo, era una opción interesante a la hora de encontrar un reemplazo. Lo que no esperaba era encontrarme con un leve problema: Ninguno de los dos funcionó en mi máquina de desarrollo, ni bien instalados. Muy extraño, porque recuerdo haberlos utilizado en el pasado, pero esta vez, no hubo caso. Les edité el código fuente, cambié extensiones y constantes. Nada.

Así es como caí en las dos soluciones que estoy utilizando actualmente y con las cuales, tengo resuelto el tema de la documentación en el mediano plazo. El primero de ellos, es un proyecto llamado Doxygen, muy conocido en el ámbito de Java y C++, pero que me sorprendió gratamente al ver que también funcionaba con PHP. Mucha gente lo utiliza (por ejemplo, la gente de KDE) y ya veo por qué: crea la documentación separada en lista y jerarquía de clases, por archivos, módulos o estructuras de datos. Además ofrece la posibilidad de generar archivos HTML, CHM, RTF, PDF, LaTeX, PostScript o man pages.

PHPXref.com

Esto parecería ser suficiente, si no fuera porque encontré otro generador, llamado PHPxRef, con una característica muy interesante: linkea toda llamada de un método, función, variable o constante, hacia el lugar del código donde está definido (aunque sea en otro archivo). Complementa a la perfección a Doxygen y como éste, son aplicaciones que se instalan en la PC (si usan windows, aunque también están disponibles para linux) y pueden utilizarse sin problemas, y sin tener PHP instalado. Si quieren ver un ejemplo de PHPxRef, pueden acceder a PHPxRef.com, donde hay una lista de documentación generada de algunas aplicaciones Open Source conocidas.

¿Pero como se documenta el código?

Esto merecería ser parte de un artículo aparte, lo cuál esto no pretende ser, pero básicamente, un standar en la documentación de código, es utilizar la sintáxis JavaDoc o PHPDoc (básicamente, lo mismo, pero con otro nombre). Si tuviéramos una clase definida en un archivo, la sintáxis PHPDoc sería:

Así, como verán, el comentario en vez de comenzar como usualmente lo hace, con /*. lo hace con un doble asterisco: /**. Esta sutil diferencia, permite que un programa pueda leer los comentarios cercanos a las declaraciones de clases o métodos, y agregar el contenido a la documentación. Así como ven palabras clave especiales (@uses, @author, @version, @package, etc), hay muchas otras para indicar, por ejemplo, los tipos de parámetros que recibe una función (@param) o el valor que la misma devuelve (@return). Para los más curiosos, les dejo una explicación sobre Como documentar código.

Y a modo de complemento, en otro sitio, fue publicado una simple explicación para setear un script en PHP utilizando MySQL para guardar los datos de la votación, y así luego poder mostrar los resultados utilizando el mismo ejemplo anterior. El código, hay que admitirlo, no es ninguna maravilla, pero logra el truco.

Lo habitual
Cuando aprendemos nuestros primeros pasos con PHP, cualquier tutorial o manual que leemos, nos enseña y vanagloria las bondades de poder incluir el código PHP directamente entre el HTML. Entonces, es muy habitual ver ejemplos del tipo:

Y como la mente y el alma de un principiante de cualquier tema, está preparada para aprender todo lo que pueda, en el menor tiempo que pueda, toma este tipo de ejemplos como "verdades universales" y comenzamos a ver código PHP embebido entre el HTML por TODOS lados. Pero no hay que preocuparse, esto no es necesariamente malo, y todos lo hicimos en menor o mayor medida al comenzar. Es un paso necesario que hay que aprender a superar.

Luego de un tiempo, y después de haber leido un poco más, aprendemos que todas las partes comunes de código que son repetitivas, pueden residir en archivos separados y ser "Incluidas" en nuestro código con tan solo el uso de una función:

Entonces, ese es el momento en que include() se convierte en nuestro mejor amigo y descubrimos, fascinados, como podemos lograr una verdadera mejora en el mantenimiento de nuestros sitios, al tener que modificar 1 solo archivo y que este cambio, se vea reflejado en TODAS las páginas que incluyan ese archivo. Hemos, señoras y señores, alcanzado el Nirvana.

Pero, lamento decepcionarlos, ningún estado de felicidad suprema es permanente. Luego de un tiempo, y a medida que seguimos utilizando este método, de repente nos vamos dando cuenta que algo simplemente no cuadra. Si bien el anterior método del include() nos salvó en su debido momento, nos vamos dando cuenta que para crear una nueva página, es necesario repetir muchas veces los include() que llaman a las partes comunes de nuestro sitio. Esto sin contar que si, por arte de magia o capricho de un jefe/cliente, la cabecera de nuestro sitio pasa de ser header.php a cabecera.php, deberiamos modificar uno a uno todos los archivos que hagan un llamado a "header.php" y hacer el reemplazo.

Es en este punto, donde cientos de programadores, todos los años se hacen la misma pregunta: ¿No habrá una manera mejor de hacer esto?

La Estructura

Primero y antes que nada, para aquellos que no deseen tipear todo el contenido del artículo en sus editores de texto, les dejo un link al código del foro para que descarguen y puedan revisar mientras leen el artículo.

A continuación debemos preparar la tabla en la base de datos que contendrá todos los temas de nuestro foro. Lo que esta tabla tendrá, es la información de nuestros mensajes, el autor del mismo, y otros datos que servirán para identificar a que Tema pertenece un mensaje. Pero mejor, veamos la estructura propuesta :

Veamos en detalle que campos tendrá nuestra tabla de Foros:

• id : Será e identificador principal de la tabla. Sirve para diferenciar cada uno de los mensajes.
• autor : el autor del mensaje.
• titulo : el titulo que tendrá el mensaje. Si este mensaje es el iniciador de un tema, será el que mostrará en el home del Foro.
• mensaje : El mensaje en si mismo.
• fecha : un campo DATETIME que indicará en que fecha se ha publicado este mensaje.
• respuestas : Si este mensaje es el iniciador de un tema, aqui se acumularán la cantidad de respuestas que reciba.
• identificador : este campo guarda el valor del id del mensaje que se está respondiendo. Si el mensaje es iniciador de un tema, entonces este campo valdrá cero.
• ult_respuesta : si el mensaje es iniciador de tema, aqui se actualizará valor de acuerdo con la fecha de la última respuesta que haya recibido. Sirve para poder mantener un orden en los foros.

La sentencia SQL anterior, pueden guardarla en un archivo.sql y correrla en su base de datos desde el phpMyAdmin, o si lo prefieren, pueden ingresarla linea por linea en un cliente de texto de mySQL ( como el mySQL monitor). Una vez que hayan creado la tabla en su base de datos, entonces podemos avanzar al siguiente paso.

Antes de ponernos a programar cualquier parte del foro, vamos a encargarnos de hacer un pequeño script que realice una tarea que vamos a repetir mucho, y que es conectarnos a la base de datos. Este script lo incluiremos en cada página en la que tengamos que acceder a la base de datos:

configuracion.php

Cómo vemos, no hay gran ciencia en este script, tan solo unas variables conteniendo la configuración de nuestra base de datos, y el código mínimo y necesario para conectarnos y guardar el recurso de conexión en una variable $con que luego utilizaremos cuando hagamos nuestras consultas.