Geplaatst op 9 March 2009, 19:02 door Mylène Reiners
in java, open source
Iedereen is zich bewust van het belang van documentatie - maar jammer genoeg is documentatie al zolang ik me kan herinneren een ondergeschoven kindje. Als een project dreigt uit te lopen, wordt documentatie zo ongeveer als eerste geschrapt.
Zelfs in projecten die niet onder tijdsdruk staan, wordt vaak niet goed (genoeg) gedocumenteerd. Op het moment dat je er diep in zit, weet je het immers allemaal wel. Vandaag bijvoorbeeld had een collega nog de opmerking "X heeft het me uitgelegd, en ik begrijp het nu". Toch maar even gevraagd datgene wat zij nu begreep, te documenteren. Een mailtje sturen naar de rest van het team werkt tijdelijk. Totdat het team de deur uit is, en er wijzigingen plaats moeten vinden...
Enter Doxygen.
Doxygen is een tool om enerzijds in een aantal formaten (html, latex, rtf, man etc.) documentatie te genereren uit gedocumenteerde source code. Anderzijds kan het documentatie genereren uit ongedocumenteerde source code.
Vooral dat laatste is wat mij betreft heel interessant.
Ik heb de windows installer gebruikt, die komt met een GUI frontend. Je kunt Doxygen ook via Ant of de command line gebruiken.
M.i. werkt het voor de gemiddelde ontwikkelaar best intuïtief. Je geeft aan van welk project je de documentatie wilt laten genereren, welke taal (in mijn geval dus Java, maar het kan ook voor o.a. C, C++, C#, PHP), welke output, en of je diagrammen wilt genereren, en waarmee.
Als je naast Doxygen ook nog GraphViz op je machine hebt staan, geeft dat wel veel voordelen... Je kunt meer en mooiere diagrammen laten genereren, inclusief class diagrams. Daarbij kun je ze een "UML look" geven, wat veel bijdraagt aan de leesbaarheid (iedereen kent ze immers al).
Nadat je alles naar wens hebt geconfigureerd (na de eerste keer kwam ik erachter dat je in de "expert" tab een paar opties aan moest zetten voor de beste resultaten), hoef je alleen nog op "Run" te drukken, en de documentatie wordt in het door jou gewenste resultaat gegenereerd. En het gaat snel, uiteraard wel afhankelijk van de grootte van je project, en het aantal opties dat je aan hebt staan.
Als je voornamelijk ongedocumenteerde code hebt, krijg je een schat aan informatie. Ik had (niet helemaal) toevallig de source code van autodeploy (waarover in een latere blogpost meer) op mijn machine staan, en heb die als basis gebruikt. Om een indruk te geven heb ik een paar screenshots toegevoegd.
Ik kan iedereen alleen maar aanraden om op het moment dat minder goed gedocumenteerde code in onderhoud genomen moet worden Doxygen te overwegen...
originele grootte
originele grootte
originele grootte
originele grootte
originele grootte
Share this | 643 keer bekeken | 4 reacties
Het klinkt allemaal erg leuk. Helaas zijn de plaatjes te klein om de tekst erin te kunnen lezen, maar wat ik me afvraag is wat het je echt oplevert. Wat gegenereert kan worden is meestal stating the obvious. Als dat voldoende beschrijvend is dan is de code meestal ook helderen inzichtelijk. Winst is dan dat je het ook buiten de code kan snappen. Maar als je kijkt naar ongedocumenteerde code (legacy?) dan is het vaak niet direct te lezen en te snappen; ik bedoel daar moet je dan even tijd in stoppen. Van die code krijg je volgens mij door de gegenereerde code alleen een schijngevoel van inzicht. Of zie ik dat verkeerd?
Misschien kun je de Ant task vanuit Maven aanroepen? Dat is standaard werk (of is dat je niet lekker werkende work-around?)
En voor alles blijft gelden garbage in, garbage out - maar het helpt al als je die garbage out snel kunt raadplegen. Het geeft meer dan schijnzekerheid (en ik zal de links naar de volledige plaatjes proberen toe te voegen :)
Iedereen is zich bewust van het belang van documentatie - maar jammer genoeg is documentatie al zolang ik me kan herinneren een ondergeschoven kindje. Als een project dreigt uit te lopen, wordt documentatie zo ongeveer als eerste geschrapt.
Zelfs in projecten die niet onder tijdsdruk staan, wordt vaak niet goed (genoeg) gedocumenteerd. Op het moment dat je er diep in zit, weet je het immers allemaal wel. Vandaag bijvoorbeeld had een collega nog de opmerking "X heeft het me uitgelegd, en ik begrijp het nu". Toch maar even gevraagd datgene wat zij nu begreep, te documenteren. Een mailtje sturen naar de rest van het team werkt tijdelijk. Totdat het team de deur uit is, en er wijzigingen plaats moeten vinden...
Enter Doxygen.
Doxygen is een tool om enerzijds in een aantal formaten (html, latex, rtf, man etc.) documentatie te genereren uit gedocumenteerde source code. Anderzijds kan het documentatie genereren uit ongedocumenteerde source code.
Vooral dat laatste is wat mij betreft heel interessant.
Ik heb de windows installer gebruikt, die komt met een GUI frontend. Je kunt Doxygen ook via Ant of de command line gebruiken.
M.i. werkt het voor de gemiddelde ontwikkelaar best intuïtief. Je geeft aan van welk project je de documentatie wilt laten genereren, welke taal (in mijn geval dus Java, maar het kan ook voor o.a. C, C++, C#, PHP), welke output, en of je diagrammen wilt genereren, en waarmee.
Als je naast Doxygen ook nog GraphViz op je machine hebt staan, geeft dat wel veel voordelen... Je kunt meer en mooiere diagrammen laten genereren, inclusief class diagrams. Daarbij kun je ze een "UML look" geven, wat veel bijdraagt aan de leesbaarheid (iedereen kent ze immers al).Nadat je alles naar wens hebt geconfigureerd (na de eerste keer kwam ik erachter dat je in de "expert" tab een paar opties aan moest zetten voor de beste resultaten), hoef je alleen nog op "Run" te drukken, en de documentatie wordt in het door jou gewenste resultaat gegenereerd. En het gaat snel, uiteraard wel afhankelijk van de grootte van je project, en het aantal opties dat je aan hebt staan.
Als je voornamelijk ongedocumenteerde code hebt, krijg je een schat aan informatie. Ik had (niet helemaal) toevallig de source code van autodeploy (waarover in een latere blogpost meer) op mijn machine staan, en heb die als basis gebruikt. Om een indruk te geven heb ik een paar screenshots toegevoegd.
Ik kan iedereen alleen maar aanraden om op het moment dat minder goed gedocumenteerde code in onderhoud genomen moet worden Doxygen te overwegen...
originele grootte
originele grootte
originele grootte
originele grootte
originele grootte
Share this | 643 keer bekeken | 4 reacties
Reacties 
Dion Lammers reageert, op March 10, 2009 om 09:10 (GMT +01:00):
@Mylene,Het klinkt allemaal erg leuk. Helaas zijn de plaatjes te klein om de tekst erin te kunnen lezen, maar wat ik me afvraag is wat het je echt oplevert. Wat gegenereert kan worden is meestal stating the obvious. Als dat voldoende beschrijvend is dan is de code meestal ook helderen inzichtelijk. Winst is dan dat je het ook buiten de code kan snappen. Maar als je kijkt naar ongedocumenteerde code (legacy?) dan is het vaak niet direct te lezen en te snappen; ik bedoel daar moet je dan even tijd in stoppen. Van die code krijg je volgens mij door de gegenereerde code alleen een schijngevoel van inzicht. Of zie ik dat verkeerd?
Mylène Reiners reageert, op March 10, 2009 om 12:53 (GMT +01:00):
@Dennis, alleen genereren van output voor gewijzigde code staat al een hele tijd op de wishlist, met moeilijkheidsgraad 10 (de hoogste)...Misschien kun je de Ant task vanuit Maven aanroepen? Dat is standaard werk (of is dat je niet lekker werkende work-around?)
Mylène Reiners reageert, op March 10, 2009 om 12:56 (GMT +01:00):
@Dion, het kan uiteraard nooit op tegen "echte" documentatie. Je krijgt wel snel een redelijk beeld (al is het maar hoe alles in elkaar genest is).En voor alles blijft gelden garbage in, garbage out - maar het helpt al als je die garbage out snel kunt raadplegen. Het geeft meer dan schijnzekerheid (en ik zal de links naar de volledige plaatjes proberen toe te voegen :)
Reageer
Top artikelen
Dennis Vredeveld reageert, op March 10, 2009 om 09:08 (GMT +01:00):
Ik gebruik Doxygen al een tijdje naar volle tevredenheid. Er zijn wel een paar dingen die ik mis. Een is de mogelijkheid om automatisch een nieuwe versie te genereren. Nu moet je zelf een cronjob o.i.d. maken die telkens de complete documentatie opnieuw genereert, i.p.v. enkel de delen die veranderd zijn. Verder zou het handig zijn wanneer er een of andere integratie met Maven mogelijk is, zodat je het direct vanuit Maven kunt starten. Daar zijn wel manieren voor maar die werken niet echt lekker.