Dokumentasjon av JavaScript
I dagens web 2.0-prosjekter er JavaScript oftere enn ikke en del av prosjektet. Men sørger du for å dokumentere skikkelig slik at utivkleren etter deg får en enkel jobb med å ta over?
Problemet med dokumentasjon
Veldig få utviklere liker dokumentasjon spesielt godt. Klart, vi liker andres dokumentasjon godt, og setter ofte høye krav til den, men vår egen dokumentasjon er det tidvis så som så med. Hvorfor er det slik?
- I stressede prosjekter blir dokumentasjon ofte nedprioritert for å bli ferdig i tide. Dette fører til at store mengde dokumentasjon må produseres i ett jafs når koden er ferdig skrevet.
- Dokumentasjon er ekstravekt når kodebasen skal vedlikeholdes
- Sålenge det er én avgrenset gjeng med utviklere som jobber på koden (eller kanskje bare én utvikler) føler man ikke alltid et behov for dokumentasjon. Vel, ihvertfall ikke før kodebasen er såppass stor at å få inn en ny utvikler blir en byrde fremfor velkommen hjelp.
- Spesifikt for JavaScript er at det ofte sorterer sammen med GUI/design-dokumentasjon, og vedlikeholdes gjerne utenfor kodebasen
I de fleste prosjekter vil dette over tid bli et problem. Uten dokumentasjon vil man blant annet få større risiko for
- Duplisert kode. Uten dokumentasjon er det ofte vanskeligere å få oversikt over kodebasen. Har man ikke tid til å lete gjennom all koden skriver man funksjonalitet på nytt
- Koden blir vanskeligere å forstå. Når koden ikke lengre ligger fremst på tunga kan den være vanskelig å bruke uten en god forklaring og noen gode eksempler.
- Vanskeligere å introdusere nye utviklere for koden din. Dette er en variant av "vanskeligere å forstå"
JsDoc
JsDoc er et verktøy som ligner mye på Javadoc, RDoc og andre. Med andre ord er JSDoc et verktøy som automatisk ekstraherer dokumentasjon fra koden din.
Noen kommentarer er nok
Fordelen ved å lage dokumentasjon gjennom å ekstrahere direkte fra koden er at dokumentasjonen ikke blir et eget dokument som må vedlikeholdes på siden av koden. Dette gjør det betraktelig lettere og mer praktisk å å dokumentere, og øker dermed sjansen for å få god dokumentasjon. I tillegg er slik dokumentasjon tilnærmet smertefri å vedlikeholde fordi den "er rett der" når du oppdaterer koden din.
Uten noe hjelp fra deg vil JsDoc i mange tilfeller hente ut noe nyttig informasjon om koden din så som hvilke objekter og funksjoner/metoder den definerer. Ved å hjelpe den litt på vei kan du også detaljere metodesignaturene. Er du virkelig i siget kan man lage rett så fin dokumentasjon.
Noen eksempler
Hvordan ser det ut? JsDoc er malbasert og utseende kan dermed tilpasses etter behov. For å vise noen maler har JsDoc-websiden flere eksempler, generert fra kildekoden til JsDoc (som er skrevet i JavaScript).
Sweet, Sunny og Spicey vil se kjent ut for alle som har hatt noe med Javadoc å gjøre. Desverre bruker alle disse løsningene frames. Men, med riktig mal kan man unngå frames også. Mad er en fresk dokumentasjonsmal, om enn noe tung i fargevalg. Er du uenig i fargevalget er det selvfølgelig en smal sak å justere CSS-en litt.
Kodeeksempler
La oss se et enkelt kodeeksempel:
/**
* @fileOverview
* Inneholder funksjoner som gjør spennende ting
*/
/**
* Gjør noe interessant
*
* @author Christian Johansen (c...@cjohansen.no)
* @param {int} times Antall ganger å gjøre noe interessant
* @param {string} msg Tekst til interessant behandling
*/
function doStuff(times, msg) {
for (var i = 0; i < times; i++) {
alert(msg);
}
}Fra dette genererer JsDoc følgende dokumentasjon:
Legg også merke til at du kan se kildekoden fra dokumentasjonen, pent formattert. Ganske nyttig.
Dokumentasjon av objektorientert kode
Det er mange måter å gjøre objektorientering i JavaScript på. JsDoc skjønner desverre ikke alle av seg selv. En ganske vanlig måte å gjøre objektorientering på (les: å lage klasser på) er metoden gjort populær av prototype:
var MinKlasse = Class.create();
MinKlasse.prototype = {
// Klassedefinisjon
}Eller varianten der du sender prototype-objektet til metoden som lager klassen:
var MinKlasse = Class.create({
// Klassedefinisjon
});
Slik kode vil uten videre bli riktig dokumentert med JsDoc. Heldigvis kan du bruke @class, @memberOf og @scope for å oppnå ønsket resultat. Følgende eksempel vil bli tolket riktig av JsDoc:
/**
* @class En beskrivelse av klassen
* @author Christian Johansen (c...@cjohansen.no)
*/
navnerom.KlasseNavn = Class.create(/** @scope navnerom.KlasseNavn.prototype */{
/**
* Konstruktør. Initialiser objekt.
*
* @memberOf navnerom.KlasseNavn
* @param {Array} param
*/
initialize: function(param) {
// Litt kode
},
/**
* En metode
*
* @memberOf navnerom.KlasseNavn
* @return {boolean}
*/
someMethod: function() {
// Litt kode
}
});
Legg spesielt merke til bruken av @scope og @memberOf.
Kjør JsDoc!
JsDoc er som nevnt implementert i JavaScript, og kan kjøres gjennom en Java-implementasjon. Dette gjør kommandoen ganske lang og knotete. I wikien til JsDoc finner du følgende tips til "executable" under Windows: Opprett en bat-fil (eksempelvis jsdoc.bat) i en mappe som er på PATH-en din, og putt inn følgende:
@echo off
set JSDOC_BASE_DIR=C:\bin\jsdoc_toolkit-1.4.0
java -Djsdoc.dir=%JSDOC_BASE_DIR%
-jar %JSDOC_BASE_DIR%\app\js.jar %JSDOC_BASE_DIR%\app\run.js
%*(Linjer knekt for visning her, kjør alt på én linje i bat-fila).
For Linux gjelder jsdoc.sh:
#!/bin/bash
export JSDOC_BASE_DIR=~/bin/jsdoc_toolkit-1.4.0
java -Djsdoc.dir=$JSDOC_BASE_DIR
-jar $JSDOC_BASE_DIR/app/js.jar $JSDOC_BASE_DIR/app/run.js
$*
Gjør filen kjørbar ( chmod u+x jsdoc.sh) og lag en symlink ( ln -s jsdoc.sh jsdoc).
Deretter kan du generere dokumentasjon med C:\>jsdoc [parametere] fil [fil...]
Hvis du stort sett bruker den samme malen kan du legge den også i bat/sh-filen:
@echo off
set JSDOC_BASE_DIR=C:\bin\jsdoc_toolkit-1.4.0
java -Djsdoc.dir=%JSDOC_BASE_DIR%
-jar %JSDOC_BASE_DIR%\app\js.jar %JSDOC_BASE_DIR%\app\run.js
-t=%JSDOC_BASE_DIR%\templates\sweet
%*Fornøyelig dokumentering!
