Xavier Amatriain
Aquest document pretén recollir tots els consells in normes bàsiques que acostumo a donar als projectistes de Enginyeria Informàtica i Enginyeria Tècnica en Sistemes Informàtics que realitzen el seu Projecte Final de Carrera al Music Technology Group de la Universitat Pompeu Fabra (http://www.iua.upf.es/mtg). Tot el que s'exposa en aquest document són opinions personals fruit de la meva pròpia experiència. Tot i això, la majoria dels consells que hi trobareu poden ser útils per a l'elaboració d'un Projecte Final de Carrera tècnic fins i tot en d'altres carreres o universitats. Us aconsello, no obstant, que comenteu totes les vostres decisions amb el vostre Director de Projecte ja que ell serà el que tingui una visió més propera del que s'espera del vostre projecte.
En aquest document es recullen consells generals relacionats amb l'execució del projecte en sí, però l'objectiu principal és la redacció d'una Memòria de Projecte adient. Tot i que pugui semblar que en un PFC tècnic aquesta part no és tan important com la implementació en sí, penseu que la Memòria que presenteu serà l'element que formarà el 80% de la impressió que sobre el projecte tindran els membres del Tribunal (l'altre 20% correspon a la defensa oral a la que també dedicarem un petit comentari).
El primer pas important a l'hora d'escriure la Memòria és dissenyar un índex. La creació d'un índex abans fins i tot de començar a escriure té molts avantatges. Per començar, tenim sempre una visió estructurada del nostre treball. Això ens permet anar escrivint apartats diferents de forma no-seqüencial sense perdre de vista el conjunt. L'índex ens ajuda també a saber si hi ha parts descompensades o parts a les que se'ls està dedicant massa espai (penseu que el número de pàgines que dediqueu a un tema hauria de ser directament proporcional a la importància que el tema en qüestió té sobre la vostra memòria).
El més curiós del cas és que, amb molt petites variacions, l'índex de qualsevol projecte d'informàtica es pot assimilar a l´índex que teniu a continuació:
El més important d'aquesta part és que ha de ser curta. Una introducció que necessiti més de 3-4 pàgines ja no és una introducció. En aquest apartat hem de situar el lector. Per a fer això hem de definir clarament l'objectiu i abast del projecte. També resulta important ``contextualitzar'' el Pojecte, és a dir explicar el contexte en que està inscrit el projecte. Per últim, hauríem de fer un petit resum (``abstract'') del projecte explicant les seves característiques principals i les eines utilitzades en poques paraules.
El que heu de fer en aquest apartat és el que en termes d'Enginyeria de Software s'anomena ``Anàlisi de Requeriments''. No puc explicar-vos aquí tot el relacionat amb l'Enginyeria de Requeriments. Segur que molts de vosaltres ja heu fet la meva assignatura d'Enginyeria de Software I. De totes maneres a la web de l'assignatura hi podeu trobar tota la informació necessària: http://www.iua.upf.es/xamat/ES1.
Però resumint molt, una Anàlisi de Requeriments vol dir descobrir QUÈ ha de fer la meva aplicació i COM ho ha de fer (durant tot el document utilitzaré la paraula ``aplicació'' de forma molt general, tot i que la finalitat del vostre Projecte pot ser una pàgina web, un algoritme, un disseny...). Els Requeriments Funcionals expliquen QUÈ ha de fer l'aplicació i els Requeriments No-Funcionals COM ho ha de fer. (Els que llegiu els apunts de l'assignatura veureu que hi ha altres categories i sub-categories però aquestes són les essencials).
Ex: Veurem un petit exemple, suposant que el nostre projecte té com a objectiu fer una ``aplicació per llegir i escriure un fitxer d'àudio''
En aquest apartat heu d'explicar les eines i els conceptes que heu utilitzat en el vostre projecte. Eines com ara un llenguatge de programació concret i idees com ara un paradigma o un algoritme. En aquest apartat hauríeu de fer un petit resum filtrat de la bibliografia que heu necessitat. Però encara més important, heu de justificar qualsevol elecció que hàgiu pres. Per exemple si heu decidit d'implementar el vostre programa en C++, aquest és el lloc on podeu parlar una mica del llenguatge, les possibles alternatives i el perquè de l'elecció. Si l'elecció no l'heu fet vosaltres sinó que ha estat condicionada per l'entorn, el Director de Projecte, etc... podeu en aquest cas valorar si l'elecció resulta apropiada o no i les raons que hi ha darrera.
Una pregunta que solen fer tots el alumnes sobre aquesta part és quin nivell de detall o profunditat han de fer servir. És a dir, si faig servir C++ haig de transcriure un manual del llenguatge? Evidentment no. Com a norma general, es dona per suposat que tot el que heu fet a la carrera ja és sabut per el lector de la vostra Memòria així que tan sols val la pena resumir molt breument els trets més importants i centrar-se en aquells que es relacionen directament amb l'objecte de la Memòria i en justificar la seva elecció.
Aquesta és la part que més variarà d'un projecte a un altre. De fet aquest capítol es podria descomposar en diversos capítols segons on estigui el focus del projecte. Per exemple ``Anàlisi'' i ``Disseny i Implementació'', etc... El títol del capítol en si també pot ser molt diferent, podríem dir-li una cosa com ``L'Aplicació'', ``El Producte'' o posar-li inclús un nom propi.
Com que aquesta part pot variar molt en el seu contingut no hi ha gaire normes generals a donar excepte que es mantingui certa coherència amb la resta de la Memòria.
Però sí resulta important mencionar com s'ha de documentar el codi. En una memòria d'Enginyeria Informàtica hi hauria d'aparèixer el mínim de codi font. De fet fixeu-vos que idealment el codi font hauria d'anar en un Annex diferenciat, amb els comentaris que faci falta. En el nucli de la memòria només hauríem d'utilitzar codi font si estem particularment orgullosos de com hem realitzat una implementació en particular o per il·lustrar un concepte (per exemple, la implementació realitzada aconsegueix reduir molt el número de línies de codi que s'han d'utilitzar per realitzar una tasca). Si no és així, millor utilitzar diagrames (UML a ser possible) i explicacions textuals. (Nota: Evidentment pot haver-hi casos concrets en que l'objectiu principal del Projecte sigui una implementació concreta i optimitzada d'un algoritme en un llenguatge X, per exemple. En aquest cas podria justificar-se una mica més l'aparició de codi font a la memòria. Però només en casos així.)
En aquest apartat haurem de referenciar les conclusions tant tècniques com personals a les que hem arribat després de fer el Projecte. És un bon lloc per explicar les desviacions que hi ha hagut respecte als requeriments inicials, temes que encara queden pendents, etc...
És important que qualsevol Memòria disposi d'una Bibliografia mínima i que aquesta sigui referenciada als diversos capítols. Heu de tenir present que a la Bibliografia ha d'aparèixer tota la informació necessària per a que algú interessat pugui trobar l'obra referenciada: Autor, Títol, Títol de la Publicació, Editorial i Any.
Els annexes poden ser molt variats i per norma general contindran allò que no és necessari llegir per entendre la memòria però que volem deixar constància. Els annexes poden contenir tan treball propi com treball d'altres que ha influït tant el nostre Projecte que considerem necessari rendir ``tribut'' d'aquesta manera.
Exemples d'Annexes són els següents:
És molt possible que tingueu en ment un capítol o apartat que no sabeu encabir en l'esquema anterior. És normal, només cal fer servir el sentit comú i utilitzar el mateix tipus de raonaments que hem utilitzat anteriorment.
(Nota: A moltes universitats s'exigeix que un Projecte Final de Carrera d'Informàtica s'inclogui un apartat de Planificació i Pressupost. Tot i que a la UPF això no és obligatori, resulta com a mínim un detall interessant sobretot per a alumnes de la carrera Superior).
El primer que ens hem de preguntar és a qui va dirigida la Memòria. I la resposta és molt simple: als membres del Tribunal. Això ha de guiar les nostres decisions respecte al to i el tipus de llenguatge a utilitzar. Els membres del Tribunal són professors de la Carrera Informàtica. Per tant és de suposar que tenen els coneixements tècnics d'un informàtic de carrera. No tots tenen perquè dominar el tema del nostre Projecte tot i que poden tenir coneixements bastant avançats de temes laterals (p.e. en l'exemple del nostre projecte, potser un membre del Tribunal no té ni idea de formats d'àudio però és un expert en programació C++). Apart d'això, sempre tindrem com a mínim un membre (normalment el mateix director) que sí domini el tema que s'està exposant.
Per tant, hem de fer servir llenguatge eminentment tècnic però sense donar per suposat coses pròpies del domini que un informàtic qualsevol pot no conèixer. En aquest sentit, hem de tenir cura de definir els termes clau la primera vegada que apareixen. Això ho podem fer perfectament a través d'un peu de pàgina que inclús pot referenciar un apartat posterior on aquest concepte s'explicarà amb més deteniment. Un altre recurs que en alguns casos pot resultar aconsellable és la realització d'un breu Glosari a la Introducció, definint els conceptes clau.
També, en la mateixa línia, resulta interessant redactar els apartats de forma que el grau de detall vagi en augment conforme es desenvolupa l'apartat. Cada apartat (inclús subapartat) hauria de començar amb un petit pàragraf que resumís el contingut del mateix de forma que algú que no vulgui entrar en detalls en tingui prou. Aquell qui li interessi l'apartat i els seus detalls tècnics seguirà llegint fins al final però un lector qualsevol pot abandonar l'apartat després de llegir el primer pàrraf seguir llegint la memòria sense problemes. Si la primera frase d'un apartat és enrevesada i poc clara, tenim molts números de perdre el lector en aquest punt.
En una Memòria tècnica hem d'intentar minimitzar les opinions i, en canvi, maximitzar els fets contrastats i les conclusions raonades. Però, tot i així segueix sent important diferenciar entre fets contrastats i opinions. Si un punt que estem exposant és un fet contrastat és important de fer-ho explícit, utilitzant, per exemple, una referència bibliogràfica. Si es tracta, per contra, d'una opinió també és important de fer-ho explícit. Per exemple, diríem ``La meva opinió, en aquest sentit, és que l'aplicació implementada en aquest projecte suposa un exemple de quin és el resultat d'aplicar un bon mètode de desenvolupament''. Evidentment, la frase anterior és una opinió de l'autor. El dubte que se'ns pot planteja és si una frase així hauria d'aparèixer en una Memòria (la meva opinió és que no). Però si decidim posar-la hem de mostrar clarament que es tracta d'una opinió i no d'un fet, utilitzan constuccions com ``la meva opinió és...'', ``dedueixo que...'', ``interpreto que...'' .
Per altra banda, hem d'anar amb molt de compte amb airmacions rotundes, sobretot si es refereixen a tecnologies conegudes. Una afirmació tipus ``HTML és un llenguatge antiquat i sense futur'' resulta poc apropiada per una memòria a no ser que (1) vagi acompanyada d'un estudi extens i seriós sobre el tema o (2) sigui una referència a un personatge reconegut que pot permetre's realitzar aquest tipus d'afirmacions.
Seguint amb el tema de les referències, és important que tingueu sempre a mà aquest recurs. Hi ha referències clàssiques que han d'aparèixer sempre que es mencioni un tema (p.e. C++ i Stroustroup). Però hi ha d'altres que no ho són tant i que també podem utilitzar per destacar lectures que han influenciat el nostre treball o perquè ens ajuden a donar suport a una opinió que estem exposant sobre un tema.
Per acabar aquest punt, un tema menor però que no ho és tant: l'ortografia i la correctesa. No es pot presentar una Memòria amb faltes d'ortografia a cada pàgina. Un fet així, desconcerta el lector (inclús el pot acabar irritant) i pot invalidar un contingut que sinó seria perfectament valid. Penseu, a més, que la Memòria es diposita, un cop aprovat el PFC, a la Biblioteca. Per tant, no oblideu tampoc els aspectes purament formals.
Per començar, hem de ser capaços de realitzar un projecte en un període temporal més o menys pre-establert. En la següent exposició (i a la resta del document) consideraré que el vostre projecte tindrà una durada de 9 mesos i que tindreu una dedicació mitja de 20 hores setmanals (evidentment amb pic i valls segons si s'apropa la data d'entrega o si teniu exàmens, per exemple). Aquest escenari coincideix més o menys amb el que es dóna als estudiants de la carrera Informàtica de la Universitat Pompeu Fabra.
Dividirem el nostre projecte en 3 etapes que coincideixen amb els tres trimestres lectius. Cadascuna d'aquestes etapes hauria de portar aproximadament el següent títol:
Els tres primers mesos de començar un projecte solen ser els que teniu encara poc temps per dedicar-hi. Teniu bastants assignatures i prou feines teniu per trobar algun moment per fer una reunió amb el Director i per començar a llegir sobre el tema en qüestió. (Si aquest no és el teu cas per qualsevol raó t'anim a que en aquest període ja comencis a treballar en el punt 2).
Per tant, es tracta d'invertir aquest poc temps que teniu amb una mica de coherència.
Per tant, el resultat d'aquesta primera fase del projecte hauria de contenir, com a mínim:
A la segona etapa hauríem de ser capaços d'analitzar i dissenyar la nostra aplicació. Aquesta fase pot variar molt segons el tipus de projecte. L'objectiu principal és, però, el mateix: aconseguir analitzar els requeriments de la fase anterior en profunditat i convertir-los com a mínim en l'esquelet d'una aplicació. Aquesta aplicació no té perquè tenir encara tota la funcionalitat però sí que hem de tenir com a mínim una primera intuïció de com es dissenyarà aquesta.
Per altra banda, durant aquesta etapa hauríem d'acabar també d'analitzar aplicacions o tecnologies semblants que existeixin. Per això, evidentment haurem de llegir, com a mínim, la bibliografia que havíem recopilat en la fase anterior.
El resultat d'aquesta fase hauria de ser una primera versió de la Memòria on estiguin els tres primers capítols gairebé complerts i una primera versió del capítol 4 (Anàlisi i Disseny). Si hem optat per el paradigma Orientat a l'Objecte i utilitzem el llenguatge UML, en aquesta fase hauríem d'utilitzar diagrames de Classe, de Seqüència, etc...
I molt important, hem de tenir ja definit un Índex definitiu de la nostra Memòria.
(Nota: En l'apartat corresponent al contingut de la Memòria acabarem de detallar com ha de ser l'índex i què ha de contenir el nostre treball escrit.)
També és aconsellable tenir, en aquest moment, una planificació de què pensem fer en els tres mesos finals. Aquest és un bon moment per fer una reflexió d'on estem en aquest moment, què queda per fer i com tenim pensat d'organitzar-ho tot per arribar al nostre objectiu.
Per últim, en aquesta tercera fase hem d'acabar de dissenyar i implementar la nostra aplicació. El resultat d'aquesta fase serà, evidentment, una Memòria finalitzada i una presentació. Fixeu-vos, però, que si heu seguit l'itinerari proposat, en començar aquest darrer trimestre tindreu ja un 75-80% de la Memòria escrita. I us podreu concentrar en implementar tot allò que us falti per tenir l'aplicació que havíeu previst.
Penseu que no hi ha res pitjor que haver d'escriure la Memòria en 15 dies a corre cuita. La impressió que se'n durà el Tribunal és que tot el Projecte s'ha fet així. Per altra banda, tampoc és gaire agradable quan estàs al mig d'un desenvolupament/implementació i ho has de deixar durant 3 setmanes perquè t'adones que la Memòria està totalment abandonada. Per altra banda, també es donen molts casos de gent que ha acabat el Projecte però simplement no el presenta perquè no vol fer la Memòria.
Per evitar això, la meva proposta és que la Memòria la comenceu a partir del primer dia seguint l'esquema que he presentat en aquest apartat. Penseu que aproximadament el 60% de la vostra Memòria el podeu escriure sense ni tan sols començar a implementar (Introducció, Anàlisi de Requeriments, Eines i Conceptes...). A més el fet d'escriure parts de la Memòria en paral·lel ajuda moltes vegades a clarificar conceptes i enfocar millor la feina que resta per fer.
Per això us proposo que, des del primer dia, utilitzeu aproximadament un 15-20% del temps que dediqueu al Projecte a fer la Memòria. Això vol dir que si dediqueu 5 dies per setmana (4 hores al dia, per exemple), el Divendres heu de dedicar-ho sempre (potser no les 4 hores però sí com a mínim la meitat) a fer la Memòria. Això us ajudarà a reflexionar sobre el treball que heu fet durant la setmana i a planificar també el que fareu la setmana següent.
Els que sabeu una mica d'Enginyeria de Software potser estareu pensant que la planificació que us he marcat sembla seguir un cicle de desenvolupament massa rígid, tipus ``Cascada''. I això ja no està de moda, on estan les metodologies àgils i el Extreme Programming?
De fet jo també estic d'acord. El procés que us he pintat jo fins ara resulta potser massa estructurat però això és simplement per un afany de simplificació. Crec que és important que primer sabeu distingir mínimament les diverses fases del cicle Requeriments/Anàlisi/Disseny/Implementació i després ja us dedicareu a barrejar-les però amb coneixement de causa.
Dit això sí que hi ha certes pràctiques de XP que ens poden ser útils. En concret, us aconsello molt que feu servir el concepte d'iteracions curtes que tinguin una durada màxima de 15 dies. Això vol dir bàsicament que cada 15 dies hem de seure, pensar sobre el que hem fet i fer una llista de ``to-do's'' (temes pendents) per a resoldre en la següent iteració. Aquesta llista ha de ser realista i l'hem d'intentar complir al 100%. Això ens pot costar al principi ja que no som conscients de quin serà el nostre ritme però ràpidament hi podem agafar pràctica.
Segons aquest plantejament, hem de mantenir sempre 3 llistes de temes pendents en paral·lel. La primera conté les tasques pels propers 15 dies amb bastant grau de detall (cada subtasca no hauria de portar més de 1 hora). La segona llista conté la llista de temes pendents a 2-3 mesos vista i és molt menys detallada. Per últim, la tercera llista conté els objectius bàsics del projecte i és la que hem de mirar de tant en tant per comprovar que no ens estem desviant massa de les previsions inicials.
El tema del Extreme Programming és molt més complert que aquesta pràctica que us proposo. Hi ha d'altres conceptes relacionats amb XP com ara el test-driven development que també us poden resultar d'utilitat. Us recomano que llegiu alguna cosa al respecte.
La presentació és la vostra exposició pública del projecte. Igual que la memòria, heu de ser conscients que la presentació ha d'anar destinada als Membres del Tribunal. Per això podeu suposar que els destinataris de la mateixa ja tenen cert coneixement del Projecte ja que s'han llegit la Memòria. Els objectius principals de la Presentació són els següents:
El segon punt també resulta molt important. No té gaire sentit que el nostre projecte parli de la realització d'un portal d'internet, per exemple, i a la presentació no fem una demostració pràctica de quin ha estat el resultat.
Per últim, i no menys important, l'objectiu de la Presentació, en el torn de preguntes del Tribunal, és contestar a preguntes. Tot i que mai podem saber complertament quines preguntes ens faran sí que hauríem de fer un esforç previ de posar-nos en la situació del Tribunal i intentar veure quines preguntes es poden plantejar. Podem passar-li la memòria a algun conegut (amb coneixements d'informàtica, evidentment) i veure quins dubtes o preguntes se li plantejen. El Director també ens pot ajudar a descobrir quins punts foscos poden haver quedat. Tingueu present que la majoria de les preguntes demanaran justificacions de perquè heu triat una cosa i no una altra. Heu de tenir algunes respostes a tots aquests temes preparades.
Espero que tot el que s'explica en aquest document us pugui resultar d'utilitat i si trobeu alguna cosa equivocada o que necessiti aclariment, si us plau envieu-me un mail a xamat@iua.upf.es.
This document was generated using the LaTeX2HTML translator Version 2K.1beta (1.48)
Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer
Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics
Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -no_subdir -split 0 -show_section_numbers
/tmp/lyx_tmpdir419tuNYsQ/lyx_tmpbuf419EusVo1/PFC.tex
The translation was initiated by Xavier Amatriain on 2003-04-02
