Sandcastle – generera dokumentation från kod

Då var det dags igen. Vi har kommit till den del av projektets livscykel när det börjar bli viktigt med dokumentation!
 
Min kollega Anders har sedan han började på projektet, för ca 6 månader sedan, efterfrågat mer dokumentation om systemet. Jag har svarat att det är bortkastad tid att ha en separat dokumentation från koden eftersom den bara kommer att bli inakuell.
 
Jag tycker att man skall namnge sina klasser, metoder, variabler m.m. så att det i möjligaste mån går att förstå vad dom används till på bara namnet. Är namnen otydliga, byt namn istället för att skriva dokumentation. Är en del av en metod svår att förstå så gör Extract Method och namnge metoden så att man förstå vad den gör istället för en kommentar.
 
Men Anders har givetviss rätt att det finns många tillfällen där namngivning m.m. inte räcker. Det måste finnas en övergripande beskrivning av vad systemet gör och hur det hänger ihop.
 
Vi har definitivt kommit till en sådan situation nu i projektet då det krävs att vi har mer dokumentation efter som vi kommer att sammarbeta med en extern part för att bygga nästa del av systemet.
 
Jag har därför tittat på hur vi kan skapa dokumentation som adderar så lite jobb som möjligt och samtidigt inte kräver att man måste läsa koden. Som du kanske vet så kan man i Visual Studio ange att man skall skapa xml dokumentation för sina klasser baserat på XML kommentarer i koden. Problemet har varit att det sen .Net 2.0 släpptes så har det inte funnits något verktyg att generera hjälp filer från denna XML dokumentation. Nu har dock Microsoft släppt ett verktyg som heter Sandcastle som gör just detta, genererar hjälp filer från XML kommentarerna och klassernas olika egenskaper.
 
Man kan också addera sin egen hjälp dokumentation som inte är direkt knyten till koden om man så önskar.
 
Med hjälp av Sandcastle så kommer jag nu att börja skapa lite mer beskrivande dokumentation över projektet och sätta samman detta med dokumentationen som genereras från våra XML kommentarer.
 
Jag har också som målsättning att all denna dokumentationen skall bli en del av det automatiska bygget så att en ny version byggs minst en gång om dagen.
 
Låter allt detta intressant så läs mer på Sandcastle bloggen.   
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s