Voorlopig onderzoeksplan Bachelorscriptie 2011 -CleanDoc- Wouter Lockefeer 0545228 Probleemstelling Een goede programmeertaal moet niet alleen efficiënte programma's opleveren, maar ook handig zijn in gebruik. Één van de eigenschappen die bijvoorbeeld Java tot een populaire taal maakt, is JavaDoc [1]. Comments in de Java-code die van speciale structuur voorzien zijn, worden door JavaDoc geparsed en omgezet in documentatie in HTML. De programmeertaal Clean [3] heeft geen dergelijk systeem en wordt op wereldschaal nog maar amper gebruikt. Dit leidt tot de volgende onderzoeksvraag: Hoe kan een zo goed mogelijk automatisch code-documentatiesysteem worden opgezet voor Clean? Ten eerste moet een methode gevonden worden om de kwaliteit van een dergelijk documentatiesysteem uit te drukken. Dit zullen we doen aan de hand van een aantal punten: Gebruiksgemak: Hoe makkelijk is het voor gebruikers om commentaar om te zetten in documentatie? Onderhoudbaarheid: Hoe makkelijk is het om het systeem aan te passen of uit te breiden naarmate de ontwikkeling van Clean vordert? Intelligentie: In hoeverre controleert het systeem of documentatie bijvoorbeeld klopt of volledig is? Documentatiekwaliteit: Hoe duidelijk en overzichtelijk vinden programmeurs de gegenereerde CleanDoc documenten? Voor dit onderzoek zal niet alleen onderzocht worden hoe een dergelijk systeem kan worden opgezet, maar zal ook een eerste versie van dit systeem worden geïmplementeerd, zodat de kwaliteit getoetst kan worden door de gebruikers van Clean zelf. Voor een gestructureerd onderzoek is gekozen voor een opsplitsing van de onderzoeksvraag in een lijst deelvragen:
- Welke informatie moet in de documentatie kunnen staan? - Wat is goede syntax voor CleanDoc commentaar? - In welke taal wordt CleanDoc ontwikkeld? - Welke parseermethodes moeten gebruikt worden? - Wat wordt het outputformaat van CleanDoc? - Hoe kan CleanDoc voorzien worden van meer intelligentie? Voor antwoorden op deze vragen zal gevraagd worden om meningen van professoren aan de Radboud Universiteit Nijmegen die werken met Clean. Ook zullen vergelijkingen worden getrokken met bestaande documentatiesystemen voor andere programmeertalen, zoals JavaDoc en Haddock [2]. Verantwoording Clean is de functionele programmeertaal die ontwikkeld wordt aan de Radboud Universiteit Nijmegen. Hoewel de ontwikkelaars en gebruikers vol lof zijn over de kracht en schoonheid van de taal, valt de taal nog in het niet bij de populariteit van andere programmeertalen. Een veelgehoorde klacht onder studenten is dat de documentatie van Clean niet altijd volledig, op orde of up to date is. Een reden hiervoor kan natuurlijk zijn dat het voor programmeurs niet makkelijk wordt gemaakt om documentatie op te stellen voor hun applicatie of library. De ontwikkelaars en gebruikers van Clean aan het Radboud zelf gaven aan de behoefte te hebben aan een geautomatiseerd documentatiesysteem vergelijkbaar met het populaire JavaDoc. Met het bestaan van een dergelijke CleanDoc zal een makkelijke, heldere en uniforme manier om documentatie aan te leggen worden bevorderd, hetgeen kan leiden tot een betere algehele documentatie voor met name de vele libraries voor de taal. Theoretisch kader De meeste programmeertalen hebben minstens één, maar vaak zelfs meerdere tools om commentaar in een bepaalde syntax om te laten zetten in beter leesbare documentatie in bijvoorbeeld PDF- of HTML-formaat. Door het gebruik van zulke automatische documentatiesystemen te bevorderen, worden gebruikers aangespoord om een betere documentatie voor hun programma's en libraries aan te leggen. In de meeste gevallen bestaan de systemen uit een parser, die commentaar uit de
programmeercode haalt en de informatie die dit commentaar bevat, om te zetten naar een leesbaarder document. Speciale syntax kan gebruikt worden om extra informatie over bijvoorbeeld betekenis en opmaak aan te geven. Methode Om de onderzoeksvraag te beantwoorden, alsmede het prototype te implementeren, zullen de deelvragen stapsgewijs behandeld worden, elk in een eigen hoofdstuk. Elk hoofdstuk zal het onderzoek omschrijven, resultaten presenteren en implementatie in het prototype omschrijven. 1. Welke informatie moet in de documentatie kunnen staan? Voor deze deelvraag zal gekeken worden naar de informatie die bestaande documentatiesystemen kunnen weergeven en zal om de mening van Cleangebruikers worden gevraagd. Als resultaat zal een lijst worden opgeleverd met alle informatie die CleanDoc moet kunnen weergeven. 2. Wat is goede syntax voor CleanDoc commentaar? Voor deze deelvraag zal gekeken worden naar de syntax voor commentaar die bestaande documentatiesystemen handhaven. Een keuze zal worden gemaakt mede aan de hand van de mening van Clean-gebruikers. 3. In welke taal wordt CleanDoc ontwikkeld? Een vergelijking zal worden gemaakt tussen Java, JavaScript en Clean, waarbij uiteindelijk een keuze wordt gemaakt voor één van de talen. 4. Welke parseermethodes moeten gebruikt worden? Een vergelijking zal worden gemaakt tussen verschillende parseermethodes, waarbij uiteindelijk een keuze wordt gemaakt voor één van de methodes. Prototype: Implementatie van de gekozen parseermethode. 5. Wat wordt het outputformaat van CleanDoc? Een aantal verschillende formaten, zoals HTML en PDF zullen kort worden toegelicht en vergeleken, waarbij in overleg met Clean-gebruikers een keuze zal worden gemaakt. Prototype: De omzetting van de geparseerde informatie naar het gekozen
outputformaat. 6. Hoe kan CleanDoc voorzien worden van meer intelligentie? Aan de hand van vergelijkingen met bestaande documentatiesystemen en meningen van Clean-gebruikers zal onderzocht worden wat wenselijke, slimme eigenschappen kunnen zijn van CleanDoc. Prototype: De gewenste eigenschappen zullen op zijn minst minimaal worden geïmplementeerd, zodat deze later uitbreidbaar en verbeterbaar zijn. Tot slot zal het ontwikkelde CleanDoc getest worden door Clean-gebruikers en zullen eventuele toekomstwensen opgesomd worden voor verdere ontwikkeling van CleanDoc. Planning Het is vooralsnog moeilijk in te schatten hoeveel tijd de verschillende onderdelen zullen kosten. De speling in tijd zal vooral impact hebben op deelvraag 6, waar gekeken wordt naar slimme uitbreidingen van het systeem. Voor de bachelorscriptie staat 9 ec, wat zich vertaalt in 252 uur. Voortgangsgesprekken, bijeenkomsten en presentaties nemen een goede 20 uur in beslag, waardoor er nog zo'n 230 uur, verspreid over ongeveer 16 weken overblijft voor het onderzoek. Hiervoor is de volgende planning opgezet, hetzij grof: Week Onderdeel Uren 9 Voorlopig onderzoeksplan af. 20 10 Inlezen in literatuur: Clean en code-documentatiesystemen 15 11 Deelvraag 1 20 12 Deelvraag 2 20 13 Definitief onderzoeksplan af. 10 14 Deelvraag 3 20 15-16 Eerste versie scriptie af. 10 17 Deelvraag 4 30 18-19 Deelvraag 5 20 20-21 Deelvraag 6 20
22-23 Testfase prototype en verwerking van commentaar. 20 24 Tweede versie scriptie af. 10 25 Presentatie 15 - Totaal 230 Literatuur [1] Sun Microsoystems - Javadoc (http://java.sun.com/j2se/javadoc/) [2] Simon Marlow 2002 - Haddock, A Haskell Documentation Tool [3] R. Plasmeijer & M. Van Eekelen 2002 Clean Language Report (http://clean.cs.ru.nl/download/clean20/doc/cleanlangrep.2.1.pdf)