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.

Seguir leyendo phpDocumentor: como doxygen pero para PHP