Archivo de la etiqueta: documentación

Mezcla de consejos para codear, versionar y documentar.

Hoy encontré la respuesta a una duda bastante específica. Cada vez que revisaba un archivo fuente de Zend Framework, PHPDocumentor o cualquier otro proyecto, veía un tag de versión (@version) en los comentarios, donde el valor era una cadena que señalaba la fecha, hora y revisión en la que se realizó el commit y el autor de este, siempre con el mismo formato. ¿Como se hacía esto automáticamente?

Haciendo una pequeña búsqueda, dí con el origen. En CVS, existía la característica de reemplazar una palabra clave del código fuente, con una propiedad del repositorio/copia-de-trabajo. SVN heredó la misma característica. Se le llama “propiedades”.

Es extremadamente útil contar con la información del Id, revisión, fecha y autor del archivo fuente, debido a que hay muchas situaciones fortuitas en las que es crítico encontrar uno o varios archivos fuente afectados por algo.

Por ejemplo, si encuentro un bug, puedo reportar que archivo y versión está afectado.

Si un tercero realiza una implementación en algún archivo fuente, que requiere una función especial, puede documentar su código, incluyendo desde y hasta que versión es compatible su código con el de la rama principal.

Esta y otras cosas más, que he aprendido en el camino, son aquellas que me gustan tener a mano y compartir, así que ¡manos a la obra!

Seguir leyendo Mezcla de consejos para codear, versionar y documentar.

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.