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!

Consejo cero: Liberar

Liberar el código, nos permite que más ojos estén atentos a los errores. OJO: Esto no es mágico. Posiblemente al principio nadie lo vea, pero que alguien lo haga en el futuro, significa que ya se obtuvo un éxito.

A veces no se nos está permitido liberar una aplicación (¿alguien mencionó trabajo?). En ese caso, a veces también se puede pensar en liberar una parte como librerías y la aplicación en sí dejarla privada (hay modelos de licenciamiento que lo permiten). Lo ideal es que ojalá todo fuera libre, pero como dije, no siempre es posible.

Primer consejo: Versionar

En mi caso, estoy utilizando Subversion (SVN para los amigos), para llevar un control de los cambios de mis proyectos. Tanto SourceForge como Google Code ofrecen soporte de repositorios SVN.

Pero solo versionar no basta. Ya hice notar lo imperiosamente necesario que es contar con un registro de la versión en cada uno de los archivos. Acá encontré como aplicar un keyword especial de SVN a los archivos fuente y así poder automatizar el reemplazo de estos datos en el archivo cada vez que se haga un commit.

Lo que hay que hacer es ubicar uno de nuestros archivos fuente (ej: micodigo.php), editarlo, agregando en algún lugar de los comentarios un $Id$ y añadirle una propiedad de SVN manualmente al archivo. Usando KDESvn no logré encontrar como aplicar la propiedad (

Un comentario sobre “Mezcla de consejos para codear, versionar y documentar.”

Deja una respuesta

Tu dirección de correo electrónico no será publicada.

Este sitio usa Akismet para reducir el spam. Aprende cómo se procesan los datos de tus comentarios.