2WUDVIXHQWHV

BoletnS7:Cmodocumentarunsistemadesoftware

Objetivo

Unsistemapobrementedocumentadocarecedevaloraunquehayafuncionadobienenalgunaocasin.Enelcasode
programaspequeosypocoimportantesquesloseutilizanduranteuncortoperiododetiempo,unoscuantos
comentariosenelcdigopodransersuficientes.Noobstante,lamayoradelosprogramascuyanicadocumentacin
eselcdigo,sequedanobsoletosrpidamenteyesimposiblemantenerlos.Elqueladedicacindeunpocodeesfuerzo
aladocumentacinsearecompensadoinclusodentrodeloslmitesdeunpequeoproyecto,constituyeunasorpresa
paralamayoradelosnovatos.

Amenosqueustedseainfalibleyvivaenunmundoenelquenadacambia,tendrquevolveraconsultarelcdigoque
yaestescrito,ypondrendudadecisionesquetomduranteeldesarrollodelmismo.Sinodocumentasusdecisiones,
seversiemprecometiendolosmismoserroresytratandodecomprenderloquepudohaberdescritofcilmenteenuna
ocasin.Lafaltadedocumentacinnoslogeneratrabajoadicional,sinoquetambintiendeadaarlacalidaddel
cdigo.Sinoposeeunantidacaracterizacindelproblema,esimposiblequedesarrolleunasolucinclara.

Aprenderadocumentarsoftwareesunatareacomplicadayexigeuncriteriodeingenieramaduro.Documentarde
formaconcisaesunerrorhabitual,peroelotroextremopuederesultarigualdeperjudicial:siescribedocumentaciones
extensas,stasatosigarnallectoryconstituirnunacargaalahoradeconservarlas.Esesencialdocumentarslolos
asuntoscorrectos.Ladocumentacinnosirvedeayudaparanadiesisuextensindesanimaalagentealahorade
leerla.

Losprincipiantestienenlatentacindecentrarsusesfuerzosentemassencillos,yaquestoslesresultanmsfciles
dedocumentar.Estoesunaprdidadetiemponoseaprendenadadelesfuerzoyseterminaescribiendouna
documentacinqueescualquiercosaexceptotil.Losprincipiantestambintiendenamostrarsereaciosconlos
problemasdedocumentacin.Estotraeconsigopocavisindefuturo:siustedsabequealgnaspectodesudiseono
esdeltodocorrecto,quealgunapartedelproblemanosehaaclaradooqueesposiblequepartedelcdigotenga
errores,dgalo!Harqueellectorahorretiempodndolevueltasaalgoqueaparentementeeserrneo,seacordarde
dndetienequemirarsiencuentraproblemasyacabarteniendounadocumentacinmstilyhonesta.

Otroasuntoescundodocumentar.Aunquealgunasvecesesconvenienteposponerlatareadeladocumentacin
mientrasserealizanexperimentos,losprogramadoresconexperienciasuelendocumentardeformametdicainclusoel
cdigoprovisional,losanlisisdeunproblemainicialylosborradoresdeundiseo.Elloscreenqueestohacequela
experimentacinseamsproductiva.Adems,dadoquehantomadoladocumentacincomohbito,lesresultanormal
documentaramedidaquevanavanzando.

Esteboletnfacilitadirectricessobrecmodocumentarunsistemadesoftwarecomoelproyecto6.170.Proporcionauna
estructuraesquemticayalgunoselementosobligatorios,perodejabajosupropiocriteriotodoloreferentealos
detalles.Esesencialquenopiensequeladocumentacinesunasuntorutinarioyaburridosilohace,su
documentacinnoservirparanadayserpenosaalahoradeleerlayescribir.Asquedocumentedeforma
consciente:pregnteseamedidaquelohace,porqulohaceysiestempleandosutiempodelaformamseficaz.

Puedecortarypegarensudocumentacineltextodecualquieradelosboletinesquelehemosfacilitado.Enconcreto,
esposiblequequierausarpartesdelboletndeproblemasparadescribirlosrequisitos.Noobstante,asegresede
indicarclaramentecualquiercambioquerealice,paraquesuayudantetcniconotengaqueemularmanualmenteel
programadiffdeUnix!

Esquema

Sudocumentacindeberatenerlasiguienteestructura.Sefacilitaunnmerodepginasorientativo,tpicodeun
proyecto6.170loquepresentamosacontinuacinsondirectrices,nounrequisito.

1.Requisitos

Laseccinderequisitosdescribeelproblemaqueseestsolventandojuntoconlasolucin.Estaseccindela
documentacinresultainteresantetantoparalosusuarioscomoparalosimplementadoresnodeberacontenerdetalles
sobrelaestrategiadeimplementacinenconcreto.Lasotraspartesdeladocumentacindelsistemanoserndeinters
paralosusuarios,nicamenteparalosimplementadores,losencargadosdelmantenimientoydemspersonal.

1. Visingeneral(hasta1pgina)Unaexplicacindelobjetivodelsistemaydelafuncionalidaddelmismo.
2. Especificacinrevisada.Silefacilitaronespecificacionesdetalladasdelcomportamientodelsistema,es
probablequeencuentrequeciertaspartesdelmismoseencuentraninfraespecificadasosonambiguas.Enesta
seccindeberaaclarartantocualquiersuposicinquehayahechosobreelsignificadodelosrequisitos,como
cualquierextensinomodificacindelosmismos.
3. Manualdeusuario(15pginas).Unadescripcindetalladasobrecmoelusuariopuedeutilizarelsistema,
quoperacionespuedellevaracabo,culessonlosargumentosdelalneadecomando,etc.Las
especificacionesdetalladasdelosformatosdeberanrelegarsealApndice.Cualquiersuposicinrelativaal
entornodeberaexplicitarseaqu:porejemplo,observesielprogramasloseejecutaenciertasplataformas,si
suponequelajerarquadeunciertodirectorioestpresente,siexistenotrasaplicaciones,etc.Juntoconla
visingeneral,estemanualdeberaproporcionartodalainformacinqueunusuariodelsistemanecesita.
4. Funcionamiento(1/2pgina).Qurecursosnecesitaelsistemaparaunaoperacinnormalyquespacioy
 tiemposeesperaqueconsuma?
5. Anlisisdelproblema(210pginas).Unadescripcinclaradelproblemasubyacente.Estoincluyeel
modeloconceptualquehaydetrsdeldiseo(yposiblementelainterfazdeusuario),sinosehatratadoya.El
anlisisdelproblemageneralmenteincluyeunoomsmodelosdeobjetodelproblema,definicionesdesus
conjuntosyrelacionesyunadiscusindeasuntoscomplicados.Losobjetosenlosmodelosdeobjetodel
problemaprocedendeldominiodelproblema,nodelcdigo.Losmodelosdeobjetodeberanincluirtanto
diagramascomocualquierrestriccintextualfundamental,ydeberanestarclaramenteexpuestosparauna
correctalegibilidad.Estapartetambindeberadescribiralternativasquehayansidoconsideradasperoquese
hanrechazado,conrazones,asuntosnoresueltosoaspectosquenohayansidototalmenteaclaradosyque
vayanasolventarsemstarde.

Puedequeloscasosdeusoleresultentilescuandoescribalaespecificacinrevisaday/oelmanualdeusuario.Un
casodeusoesunobjetivoespecficoyunalistadeaccionesqueunusuariollevaacaboparaconseguirdichoobjetivo.
Unclientepuede,entreotrascosas,examinarlalistadeaccionesparadecidirsilainterfazdeusuarioesaceptable.Si
lacoleccindecasosdeusoabarcatodoslosobjetivosdeseadosporelusuario,elclientepuedetenerlaseguridadde
queelsistemacumplirconsuobjetivo.

2.Diseo

Laseccindediseodesudocumentacinproporcionauncuadrodealtoniveldesuestrategiadeimplementacin.

1. Visingeneral(1/23pginas).Unavisingeneraldeldiseo:organizacindealtonivel,cuestionesde
diseoespecialmenteinteresantes,usodelibrerasyotrosmdulosdeterceroseindicadoresdeaspectosno
resueltosoproclivesalcambio.Tambinincluyeproblemasconeldiseo:decisionesquepuedenresultar
errneasylosanlisisdelasconsecuenciasentrelaflexibilidadyelfuncionamientoquepuedenserjuzgadas
negativamente.
2. Estructuraentiempodeejecucin(15pginas).Unadescripcindelaestructuradelestadodel
programaenejecucin,expresadacomounmodelodeobjetodecdigo.stedeberaocultarlas
representacionesdelostiposdedatosabstractossupropsitoconsisteenmostrarlasrelacionesentreobjetos.
Losmodelosdeobjetodeberanincluirtantodiagramascomocualquierrestriccintextualfundamental,y
deberanestarclaramenteexpuestosparaunacorrectalegibilidad.Lasrepresentacionesdelostiposdedatos
deberanexplicarse(consusfuncionesdeabstraccineinvariantesderepresentacin)siesasrepresentaciones
sonpococomunes,especialmentecomplejasodecisivasparaeldiseoglobal.Observequelasfuncionesde
abstraccinylosinvariantesderepresentacindeberanapareceranasensusitionormalenelpropiocdigo.
3. Estructuradelmdulo(15pginas).Unadescripcindelaestructurasintcticadeltextodelprograma,
expresadacomoundiagramadedependenciaentremdulos.Deberaincluirlaestructuradelpaqueteymostrar
tantolasinterfacesdeJavadelprograma,calendario,materialdeclase,trabajos,exmenes,lecturas
obligatorias,otrasfuentes,prcticas,presentaciones,herramientasyproyectos,comolasclases.Noesnecesario
exhibirlasdependenciasdelasclasesenlaAPIdeJavadelprograma,calendario,materialdeclase,trabajos,
exmenes,lecturasobligatorias,otrasfuentes,prcticas,presentaciones,herramientasyproyectos.
SuMDD(diagramadedependenciaentremdulos)deberaestarclaramenteexpuestoparaunacorrecta
legibilidad.Expliqueporquseeligiesaestructurasintcticaenparticular(ej.:introduccindeinterfacespara
eldesacoplamiento:qudesacoplanyporqu),ycmoseutilizaronlospatronesdediseoconcretos.

Paraexplicarladescomposicinyotrasdecisionesdediseo,expongaqueaportansimplicidad,extensibilidad(facilidad
paraaadircaractersticasnuevas),particionalidad(losdistintosmiembrosdelequipopuedentrabajarenlasdiferentes
partesdeldiseosinnecesidaddemantenerunacomunicacinconstante)uobjetivossimilaresrelativosalaingeniera
desoftware.

3.Pruebas

Laseccindepruebasdesudocumentacinindicaelenfoquequeustedhaelegidoparaverificaryvalidarsusistema.
(Enunsistemareal,estopodraincluirtantolaspruebasdeusuarioparadeterminarlaidoneidaddelsistemacomo
solucinalproblemadescritoenlaseccinderequisitos,comolaejecucindesuitesdepruebaparaverificarla
correccinalgortmicadelcdigo).Delmismomodoquenodeberacomunicareldiseodesusistemapresentandoel
cdigooinclusoenumerandolasclases,nodeberanicamenteenumerarlaspruebasrealizadas.Envezdehaceresto,
expliquecmoseseleccionaronlaspruebas,porqustasbastaron,porquunlectordeberacreerquenoseha
omitidoningunapruebaimportanteyporqudeberacreerqueelsistemarealmentefuncionarcomosedeseecuando
sepongaenprctica.

 Estrategia(12pginas).Unaexplicacindelaestrategiageneraldelaspruebas:blackboxy/oglassbox,top
down(dearribahaciaabajo)y/obottomup(deabajohaciaarriba),tiposdetestbeds(bancosdeprueba)y
manejadoresdetestsquesehanutilizado,fuentesdedatosdeltest,suitesdeprueba,mtricadecobertura,
comprobacinentiempodecompilacinfrenteasentenciasentiempodeejecucin,razonamientossobresu
cdigo,etc.Esposiblequequierausartcnicasdistintas(ocombinacionesdetcnicas)enlasdiferentespartes
delprograma.Justifiquesusdecisinencadacaso.

Expliquequtipodeerroresesperaencontrar(yculesno!)consuestrategia.Comentequaspectosdel
diseodificultaronofacilitaronlavalidacin.

2. Resultadosdeltest(1/22pginas).Resumendequpruebassehanrealizadoyculesno,siesque
quedaalguna:qumdulossehanprobado,ysisehanprobadoafondo.Indiqueelgradodeconfianzadel
cdigo:Qutipodedefectossehaneliminado?Culessonlosquepodranquedar?
4.Reflexin

Laseccindereflexin(vulgarmenteconocidacomo"postmortem")deldocumentoesdondepuedehacer
generalizacionespartiendodexitosofallosconcretos,hastallegarformularreglasqueusteduotrospuedanutilizaren
elfuturodesarrollodesoftware.Qufueloquemslesorprendi?Quhubieradeseadosabercuandocomenz?
Cmopodrahaberevitadolosproblemasqueencontrduranteeldesarrollo?

1. Evaluacin(1/21pginas).Loqueustedconsiderexitosofracasosdeldesarrollo:problemasdediseo
noresueltos,problemasdefuncionamiento,etc.Identifiqueculessonlosrasgosimportantesdesudiseo.
Sealetcnicasdediseooimplementacindelasquesesientaespecialmenteorgulloso.Expliqueculesfueron
loserroresquecometiensudiseoylosproblemasquecausaron.
2. Lecciones(0,21pgina).Quleccioneshaaprendidodelaexperiencia:cmopodrahaberlohechodeotra
formaunasegundavez,ycmoloserroresdediseoeimplementacinpuedencorregirse.Describaqu
factorescausaronproblemas,comohitoserrados,oerroresylimitacionesconocidos.
3. Erroresylimitacionesconocidos.Dequmanerasuimplementacinnollegaaalcanzarlaespecificacin?
Seaexacto.Aunqueperderpuntosporerroresycaractersticasnopresentes,obtendrpuntosparcialespor
identificardemaneraexactaesoserroresyelorigendelproblema.

5.Apndice

Elapndicecontienedetallesdebajonivelacercadelsistema,quenosonnecesariosparacomprenderloenunnivel
superior,peroqueseexigenparausarloenlaprcticaoparaverificarafirmacionesrealizadasencualquierpartedel
documento.

1. Formatos.Unadescripcindetodoslosformatosadoptadosogarantizadosporelprograma:paraunfichero
E/O(ficheroparaentradaysalidadedatos),argumentosdelalneadecomando,dilogosdeusuario,formatos
delosmensajesparalascomunicacionesenred,etc.stosdeberandesglosarseenformatosvisiblesparael
usuario,quesonparteconceptualdelosrequisitosvisiblesparaelusuarioydelmanualdeusuario,yen
formatosinterioresqueconstituyenunaparteconceptualdeotroscomponentesdesudocumentacin.
2. Especificacionesdelmdulo.Deberaextraerlasespecificacionesdesucdigoypresentarlasporseparado
aqu.SiescribesuscomentariosenelestiloaceptadoporJavadocconeldocletde6.170,podrgenerar
documentosdelaespecificacindeformaautomticaapartirdelcdigo.Laespecificacindeuntipoabstracto
deberaincluirsuvisingeneral,camposdelaespecificacineinvariantesabstractas(restriccionesde
especificacin).Lafuncindeabstraccinyelinvariantederepresentacinnoformanpartedelaespecificacin
deuntipo.
3. Casosdeprueba.Idealmente,subancodepruebasleetestsdeunarchivodecasosdepruebaenunformato
queresultacmododeleeryescribir.Noesnecesarioqueincluyacasosdepruebamuyextensosporejemplo,
simplementepodraobservareltamaodeunaentradaaleatoriageneradapararealizarpruebasdeestrsy
proveeralprogramaquegenerlostests.Indiqueculeslautilidaddecadagrupodetests(ej."pruebasde
estrs,entradasenormes","pruebasdeparticin,todaslascombinacionesde+//0paraargumentosenteros").

Documentacindelcdigo

Comentariosaniveldeespecificacin

Tiposdedatosabstractos.Cadatipodedatosabstractos(claseointerfaz)deberatener:

1. Unaseccindevisingeneralquedunaexplicacindeunaodoslneassobrequobjetosdeltipo
representanysisonmutables.
2. Unalistadecamposdeespecificacin.Podrahaberslounoporejemplo,unconjuntopodratenerel
campoelemsrepresentandoalconjuntodeelementos.Cadacampodeberatenerunnombre,untipoyunabreve
explicacin.Podraresultarletildefinircamposderivadosadicionalesquefacilitaranlaescrituradelas
especificacionesdelosmtodosparacadaunodestos,deberaindicarqueesderivadoyexplicarcmoseha
obtenidoapartirdelosotroscampos.Puedequehayainvariantesdeespecificacinquerestrinjanlos
posiblesvaloresdeloscamposdelaespecificacinsiesas,deberaprecisarlos.

Especificacionesdelmtodo.Todoslosmtodospblicosdelasclasesdeberantenerespecificacioneslosmtodos
privadoscomplicadostambindeberanespecificarse.Lasespecificacionesdelmtododeberanseguirla
estructurarequires(requiere),modifies(modifica),throws(lanza),effects(resulta),returns(devuelve)queaparece
descritaenelboletndeespecificacionesyenclase.Observequeparaelcurso6.170,puedesuponerquelos
argumentosnosonnulos,denoespecificarselocontrario.

Comentariosaniveldeimplementacin

Notasparalaimplementacin.Loscomentariosdeunaclasedeberanincluirlossiguienteselementos(loscuales,en
elcasodeclasesdestacadas,aparecentambinenlaseccinEstructuraentiempodeejecucindeladocumentacin
deldiseo):

1. Unafuncindeabstraccinquedefinacadacampodelaespecificacinenfuncindeloscamposde
representacin.Lasfuncionesdeabstraccinsolamentesonnecesariasparalasclasesquesontiposdedatos
abstractos,ynoparaclasesdetipoexcepcionesocomocualquierobjetodelaGUI.
2. Uninvariantederepresentacin.LasRIs(implementacionesdereferencia)sonnecesariasparacualquier
clasequeposeaunarepresentacin(ej.nolamayoradelasexcepciones).Esmuyrecomendablequepruebelos
 invariantesenunmtododondeseaviable.Tengacuidadoalincluirensusinvariantessuposiciones
acercadeloquepuedeonopuedesernulo.
3. Paralasclasesconrepresentacionescomplejas,aadaunanotaqueexpliquelaeleccindela
representacin(tambinconocidacomorepresentacinracional):quanlisisdeventajasydesventajasse
realizaronyqualternativassehanconsideradoyculessehanrechazado(yporqu).

Sentenciasentiempodeejecucin.stasdeberanutilizarsejuiciosamente,comoseexplicenclase.Puede
consultarMaguireSteve,WritingSolidCode,MicrosoftPress,1995,dondeencontrarunadiscusinmsextensasobre
laformaenquelassentenciasentiempodeejecucinpuedenmejorarlacalidaddesucdigo.

Comentarios.Deberacomentarsucdigocuidadosamenteyconbuengusto.Lasdirectricesestilsticasseencuentran
disponiblesenelboletndelaGuadeestilodeJavaPrograma,calendario,materialdeclase,trabajos,exmenes,
lecturas,otrasfuentes,prcticas,presentaciones,herramientasyproyectos.Sideseaobtenerunaexcelentediscusin
sobrecomentariosdeestiloyestinteresadoenrecibirmuybuenosconsejossobrelaprogramacinengeneral,
consulteKernighanBrianW.andPikeRob,ThePracticeofProgramming,AddisonWesley,Inc.,1999.