MP08 - UF4: Control de versions i documentació

Documentació d'aplicacions

Per desenvolupar un projecte informàtic cal generar molts tipus diferents de documentació a cada fase del projecte. Els elements que s’han de documentar depenen de la metodologia utilitzada per planificar el projecte. Per exemple, si s’utilitza una metodologia en cascada la documentació ha de ser exhaustiva, mentre que en el cas d’aplicar metodologies àgils el nombre d’elements és molt menor.

Entre els diferents tipus de documentació cal destacar la documentació del codi, ja que els encarregats de generar aquesta documentació són els programadors i aquesta s’inclou en forma de comentaris al codi font dels programes, encara que és possible extreure-la (en format HTML, per exemple) per consultar-la externament.

Per altra banda, com que habitualment en el desenvolupament d’un projecte informàtic hi participa més d’una persona, també és molt habitual trobar la documentació com a lloc wiki. A diferència de la documentació del codi, que és generat automàticament a partir dels comentaris, la documentació d’un lloc wiki és escrita pels diferents membres del projecte.

S’ha de diferenciar entre els formats de documentació i les eines per generar la documentació externa, ja que un mateix generador pot acceptar un o més formats diferents, però un format no pot barrejar-se amb els altres.

També cal destacar que la utilització d’un format o altre no depèn només del llenguatge, sinó que diferents biblioteques o entorns de treball poden fer servir formats diferents. Per exemple, Dojo, un entorn de treball (framework, en anglès) per a JavaScript, fa servir el seu propi format de documentació, com podeu veure a continuació:

// summary:
// Representa un llibre.
// titol: Integer
// Títol del llibre
// autor: String
// Autor del llibre
function Llibre(titol, autor) {}

La mateixa informació documentada en format JSDoc, un altre format de documentació per a JavaScript, és:

/**
* Representa un llibre.
* @constructor
* @param {number} titol - Títol del llibre
* @param {string} autor - Autor del llibre
*/
function Llibre(titol, autor) {}

Tots dos formats són aplicats a una funció en el llenguatge JavaScript, però el format és completament diferent. Tingueu en compte que l’última paraula sobre el format que cal utilitzar la té el cap del projecte, ja que al capdavall la documentació generada és la mateixa en tots dos casos.

Avantatges de documentar el codi

La tasca de documentar el codi de l’aplicació fent servir comentaris no només serveix perquè pugui ser consultat per tercers, sinó per a vosaltres mateixos, ja que al llarg de la vida d’un projecte cal fer canvis, millores i manteniment.

Per exemple, potser us heu d’encarregar d’arreglar una funció que vau implementar fa més de sis mesos, i durant aquest temps segurament heu estat treballant en altres projectes. Si el codi està correctament documentat, no us costarà gens entendre com funciona, però, si no hi ha cap tipus de documentació, haureu de depurar i inspeccionar el codi per entendre de nou el seu funcionament. Un altre cas molt habitual és haver de treballar amb codi de tercers. Si aquest codi no està documentat, el temps que trigareu a entendre com funciona i com solucionar el problema o aplicar-hi els canvis augmentarà enormement.

En el cas de treballar en projectes de programari lliure aquesta tasca és encara més important, ja que el codi s’utilitza i es modifica no només pel vostre equip de desenvolupament, sinó per qualsevol persona interessada. En aquests casos cal parar especial atenció a la documentació dels components públics de l’aplicació perquè són els elements als quals tindran accés altres desenvolupadors.

En qualsevol cas, cal tenir en compte que, igual que en el cas dels comentaris, una documentació incorrecta o desactualitzada és pitjor que una documentació inexistent, ja que els usuaris confien en la veracitat.

Nosaltes no parlarem dels comentaris que pogueu posar (i heu de posar) dins el codi per a saber què fa un troç de codi sinó de la documentació que podem generar, de forma automàtica, que inclourà les classes, funcions i altres característiques del programari gràcies a uns comentaris que posi al meu codi.

Aquesta documentació que generarem serà en format web i permetrà saber a la resta de programadors com utilitzar les nosters classes o funcions.

Si mireu el mercat actual trobareu moltes eines que fan aquesta feina - javadoc per a llenguatge java, PhpDocumentor per a llenguatge php - , algunes només centrades en algun llenguatge específic, altres més globals com vol ser NaturalDocs. En aquest mòdul utilitzarem PhpDocumentor per documentar el codi generat amb php. Generarem una documentació més aviat tècnica.