Ohjelmistokoodin ohjelmoinnin apuvälineet

Abstract

Tämän opinnäytetyön aiheena oli selvittää ohjelmistokoodien dokumentointia ja kommentointia helpottavien apuohjelmien toiminnallisuutta, ominaisuuksia ja niiden soveltuvuutta ohjelmistontuotantoprojektien asettamiin tarpeisiin. Lähtökohtana oli löytää apuohjelmia, jotka keventäisivät ohjelmoijan taakkaa dokumentoinnin tekemisessä ja siten madaltaisivat kynnystä dokumentaation tuottamiseen. Tutkielman alussa käsiteltiin dokumentoinnin periaatteita ja tutustuttiin ohjelmistoprojektin etenemiseen, sekä sen aikana tuotettaviin dokumentteihin. Tämän osuuden jälkeen esiteltiin Java-ohjelmointikielen periaatteita ja yleisesti sovittuja käytäntöjä, jotka eivät suoranaisesti liity dokumentointiin, mutta joiden huomioon ottaminen on tärkeää. Tutkielmassa tutustuttiin muutamiin ohjelmiston dokumentoinnin kannalta mielenkiintoisiin apuohjelmiin. Näitä ohjelmia esiteltiin teoriassa ja niiden ominaisuuksiin, käyttöön ja toimintaan tutustuttiin yleisellä tasolla. Ohjelmien soveltuvuutta käytännön tarpeisiin arvioitiin niiden tarjoamien ominaisuuksien perusteella. Käytännön osiossa sovellettiin hyödyllisimmiksi arvioituja apuohjelmia todellisen kaltaisessa esimerkkiprojektissa. Jokaisen ohjelman kohdalla arvioitiin sen hyvät puolet ja todettiin mahdolliset puutteet ja ongelmat. Dokumentaation puuttuminen myönnetään suureksi ongelmaksi etenkin ohjelmistoissa, jotka vaativat ylläpitoa koko elinkaarensa ajan. Dokumentaation tekeminen koetaan ohjelmiston kehityksen aikana turhaksi ja liikaa aikaa vieväksi, minkä seurauksena se jätetään helposti tekemättä kokonaan. Hyvin tehdyllä dokumentaatiolla kuitenkin säästetään työtunteja ylläpidon aikana. Dokumentaation tekemistä helpotetaan useilla apuohjelmilla, joiden tarjoamaan hyöty ja oikopolut eivät kuitenkaan poista vastuuta dokumentaation tekemisestä ohjelmoijalta. Dokumentaation rungon automaattiseen tekemiseen JAutuodoc-ohjelman avulla päädyttiin, koska olemassa oleva runko painostaa ohjelmoijaa täydentämään sen todelliseksi käytännölliseksi dokumentiksi.

The purpose of this thesis was to determine the functionality, features and the suitability of software code documenting utility programs based on the needs of software development project. The main idea was to find utility programs that would lighten the burden of writing documentation for software and thereby lowering the bar for producing the documentation. At the first part of this thesis the main principles of documentation were introduced, also the progression of software project was studied. After this Java programming language was demonstrated and with it some principles and general rules that are not directly related to documenting, but are important things to be aware of. Some interesting utility programs for documenting software code were studied in this thesis. Their features, usage and operation were portrayed in general level. The suitability of these programs for real software projects was estimated by the basis of the functionality they theoretically were able to provide. On the hands-on part of the thesis the most serviceable programs were studied in a real-like project. Every programs good applicable features and also possible flaws and problems were assessed individually. The absence of software documentation is noted as a great fault, especially in software which requires maintenance through its whole life span. Still creating the documentation is considered meaningless and time consuming during the development phase and therefore it's neglected. Good documentation would save a lot of working time during the maintenance period of the life cycle. Creation of the documentation can be helped with many utility programs. Their usage doesn't remove the responsibility of producing the documentation from the coder. Creating the base for the documentation with the tool JAutodoc, was considered to be the best way to “force” coders to write, actually just complete, the documentation.