Archivo de la etiqueta: phpdocumentor

Gonium, nuevo demo y nuevos componentes

Gracias a la wena onda de Tecnoman, que se auspicio con hosting y me dejo hincharle las pelotas para que instalara PDO en un servidor en producción, tengo el demo de Gonium en un hosting nuevo. Ahora intentaré de algún modo recompensar aquello, posteando más seguido en tecnosquad.org.

Aprovechando eso, subí una copia más reciente.

Hace unos días agregué al trunk del repositorio, una copia propia del proyecto zend-framework-datagrid, con la diferencia de que mi copia permite traducirlo con Zend_Translate y los comentarios están corregidos. También corregí unos warnings menores. Además le cambié el prefijo a las clases de “Core_” (originalmente en zf-datagrid) a “Rox_”, para darle concordancia a mi estructura de directorios. Podría decir entonces que es un pequeño fork :B

También agregué todo jQuery UI al directorio público. Una ejemplo de esto es la pequeña demostración con el efecto acordeón que le agregué al widget de Login.

Y por último, agregué un directorio con XML’s en formato docbook, para poder usarlos en conjunto con la documentación creada con phpDocumentor.

Espero tener una documentación un poco más completa más adelante.

phpDocumentor: como doxygen pero para PHP

Documentar el código es más que dejarlo bonito. Es hacerlo entendible.

“Comentar el código es como limpiar el cuarto de baño; nadie quiere hacerlo, pero el resultado es siempre una experiencia más agradable para uno mismo y sus invitados”
— Ryan Campbell

Uno de los propósitos iniciales de este blog, era combatir mi inquietante amnesia. No se ustedes, pero me es muy frecuente, que después de muchos días, semanas o meses sin ver el código que estaba trabajando, termino olvidando que hacía o como funcionaba.

“Ley de Alzheimer de la programación: si lees un código que escribiste hace más de dos semanas es como si lo vieras por primera vez”
— Via Dan Hurvitz

Hay solo una forma de combatirlo: documentando.

Será una lata, pero creo (seriamente) que los lenguajes de programación debieran mandar advertencias cuando no documentamos el código fuente.

Cuando estuve en inserto en el proyecto GDT, me topé de cerca con Doxygen, una excelente herramienta para documentar el código en función de etiquetas especiales insertas en los comentarios. Muchos años antes, me tocó conocer otra grandiosa herramienta, que ayer re-descubrí: phpdocumentor.

¿Que tiene de fantástico?

Tiene varios detalles que lo hacen un amor:

  • Esta escrito en PHP.
  • En su documentación incluye los tags especiales, con ejemplos, para escribir correctamente los comentarios.
  • Funciona por interfaz web y por consola. Posibilitando automatizar el proceso de documentación
  • Se puede configurar, guardando un archivo personalizado .ini con las opciones. Esto permite automatizar más aún el proceso.
  • Exporta a varios formatos, incluyendo HTML, PDF y CHM. Incluso tiene diversas plantillas para producir distintos estilos de HTML. También se pueden personalizar estas plantillas.

Sin duda debe tener más gracias, pero con eso es suficiente por ahora.

Ejemplos

Para probar, documenté TODAS las clases de Gonium y dejé copia acá. Sin ir más lejos, la documentación del API de Zend Framework está producida con phpDocumentor.

Sugerencia

Ser buen programador, no solo significa adoptar las mejores convenciones para escribir el código, usar el mejor IDE (esto es una estupidez, pero lo he escuchado), presumir el uso de patrones de diseño novedosos o presumir de código limpio y óptimo. Documentar es una tarea básica que DEBIERA SER OBLIGATORIA. No solo si sufres algún problema de memoria (con la de tu cabeza, no con la del PC) como yo.

Además es mucho más tedioso documentar un montón de clases ya escritas, que no sabes exactamente que hace, que comenzar documentando desde le principio. Si estas comenzando un proyecto, HAZLO YA, sino TAMBI蒒.

Caso personal

En Gonium hay algunas cuantas clases, que en su momento me pareció bueno crear mientras se me ocurría como implementarlas (por ahí por febrero de este año). Ahora no recuerdo que diablos quería hacer con ellas :B

Fuente de las citas: Variable not found: Otras 101 citas célebres del mundo de la informática.