Miten dokumentoit/kommentoit koodisi? Kirjoitatko komentin jokaiseen riviin/metodiin/luokkaan/pakettiin tai luotatko selkeisiin nimiin ja vain hankalimpien kohtien kommentointiin? Mitä dokumentoit koodikommenttien ulkopuolella?
Dokumentointi/kommentointi
juu
7662
0Äänestä
Muut lukivat myös
Odottaa vastausta
Näihin keskusteluihin ei ole vielä vastattu. Ole ensimmäinen.
Vastaukset 7
Vanhimmat
Miten ylipäätäänkin dokumentointi tehdään niin, että siitä on jotain hyötyäkin? Entä UML, mikä se on ja liittyykö se asiaan jotenkin? Aina on niin kiire, ettei ehdi funtsia tällaisia "toisarvoisia" asioita.
Jos jollain on tarjota hyviä linkkejä aiheesta, niin voisitko ystävällisesti postata ne tänne? Kiitos!
Olen itsekin miettinyt samaa asiaa. Minä väännän javadoc:n kaikista julkisista metodeista ja kerron myös siinä luokan tehtävän.
Itse UML-dokumentointiin tiedän olevan ainakin kaksi koulukuntaa, toinen koulukunta vääntää UML:ää käyttäen sitä pelkästään dokumentoinnin notaationa, toinen koulukunta taas näkee UML:n suunnittelun välineenä ja siten myös sillä ikään kuin automaattisesti syntyy tietty dokumentaation pohja.
Näistä ensimmäinen koulukunta taitaa olla tällä hetkellä vallitseva siellä missä UML:ää käytetään.
UML:llä jo jollakin välineellä (Rose, Visual Paradigm jne...) on aika kätevää lähteä suunnittelulähtöiseen ohjelmistokehitystapaan, se vain vaatii valtavasti kokemusta, muuten joutuu välissä tulemaan nurinpäin eli koodaamaan ja hakemaan sitä ratkaisua.
Suunnittelulähtöisessä kehityksessä, siis softa suunnitellaan (mallinnetaan) ensin UML:ksi ja voidaan jopa tehdä niin pitkälle että siitä generoituu valmiita koodipohjia.
Tätä lähestymistapaa ei varmaan kovin paljoa käytetä, koska vaatii kokemusta ja taitaa olla aika aika kallista, kuun dokumentoinnin kustannukset pitää pystyä piilottamaan.
Itse huomasin UML:n vahvuuden siinä kun väänsin luokkakaavioita ja sekvenssikaavioita käyttötapauksista. Oli kohtuullisen kokoisesta softastakin aika helppoa löytää oleellinen toiminnallisuus ja päästä kohtuullisen nopeesti jyvälle missä kohtaa koodissa piti mitäkin muuttaa tai korjata, kun tutki ensin asiaa sekvenssikaaviosta.
Kehitysvälineissä on kätevä ominaisuus millä pääsee notaatiosta suoraan sitä vastaavaan softaosioon käsiksi.
Tarkastin kerran tässä erään toisen tekemän sovelluksen jossa oli suunnitteludokumentaatio UML:llä. Aika nopeesti pääsi kiinni oleellisiin asioihin.
Tosin UML ei ole itse tarkoitus, se ei auta asiaa jos sitä käytetään huonosti.
Jään odottamaan milloin kehitysvälineisiin tulee ominaisuus jolla debuggauksessa näkyykin sekvenssikaavio jossa viestit sitten kulkevat askeltamalla niitä.
Voit myös käyttää UML:ää avuksi tutkimalla toisen tekemää koodia oppiaksesi siitä, java-luokat vain kehitysvälineeseen ja käännät ne siellä UML:ksi. Tosin sekvenssikaavioita ei saa koska käyttötapaukset eivät ole yksiselitteisiä.
Jos ajatelaan UML:ää dokumentoinnin välineenä, niin kuvat kertovat paljon, mutta vaativat aina mukaan tekstuaalista kommentointia. Liian usein olen nähnyt nämä kaksi erotettavan toisistaan. UML-kuvat, luokkakaaviot, sekvenssikaaviot, tilakaaviot, vaativat aina tuekseen selostuksen, joka kertoo mitä kuvassa tapahtuu. Näitä samoja tekstejä voi sitten käyttää koodin kommentteina (luokkien ja metodien kuvauksina) ja javadocissa. Monimuutakaisen koodin tai rajapinnan kuvaaminen vaatii mielellään kaikkia mainittuja, toisiaan tukevia menetelmiä.
UML on tapetilla. Löytyykö jostain maksutonta ohjelmaa jota kannattaisi kokeilla?
http://www.visual-paradigm.com/
Lataa Community Edition, se ilmainen. Jos yrittää tulostaa kuvia, vetää visual-paradigm tekstit kuvien päälle jote joutuu ottamaan kuvakaappauksia se on ilmaisversion haitta.
Onnistuin jonkun kokeiluversion maksullisesta isommasta paketista lataamaan, ja se integroitu kätevästi suoraan Eclipseen.
Sit kannattaa tsekata löytyyko Poseidon:sta ilmaista versiota. http://www.gentleware.com/index.php
En ole ko. softaa juurikaan käyttänyt.
visual-paradigm on aika lailla Rosen kaltainen, kuulin että Rational Rosestakin pitäis olla joku kokeiluversio. Pitäis löytyä IBM:n sivujen kautta.
Kannattaa huomioida että UML-mallinnustyökalut vaativat tehoa koneesta kun on isompi suunnitteludokumentaatio työn alla, koska joutuvat ylläpitämään kaikenlaisia linkityksiä. Eli siis aivan sama ongelma kuin kaikenmaailman AutoCad:ien, ja piirilevy Cad:ien kanssa.
Mun PIII 750Mhz jaksaa kohtuullisesti vauhdissa kun teen pienempiä juttuja.
Together tuntuu olevan tällä hetkellä ehdottomasti "kuumin" suunnitelutyökalu. Community Editionin voi ladata täältä http://www.borland.com/products/downloads/download_together.html . Tolla versiolla pystyy exportaamaan kaaviot kuviks ilma kuvakaappausta.
En dokumentoi ollenkaan eivätkä nimetkään aina kovin selkeitä ole (koska tulee aina tarve keksiä joka asialle joku lyhennys, tms.). Väännän kyllä työkseni koodia/ohjelmia, mutta en missään varsinaisessa softa firmassa. Ohjelmistojen speksaus ja dokumentointi on ihan tuntemattomia käsitteitä työpaikallani ja pelkästään itseäni varten en viitsi alkaa mitään dokumenttejä/speksejä vääntämään ;-) (Näin kärjistettysti ilmaistuna...)