OHJELMOINNIN TYYLISÄÄNTÖJÄ

Transkriptio

1 Ohjelmoinnin tyylisääntöjä Sivu 1 OHJELMOINNIN TYYLISÄÄNTÖJÄ Ohjelmointityylillä tarkoitetaan sääntöjä lähdekielisten ohjelmien kirjoittamiseen. Kääntäjähän hyväksyy varsin monella tavalla kirjoitetut ohjelmat, joten on ohjelmoijan vastuulla tehdä ohjelmistaan mahdollisimman ymmärrettäviä ja helposti luettavia. On tärkeää, erityisesti työelämän ohjelmistotuotannossa, että ohjelmat kirjoitetaan siten että myös toiset voivat lukea ja ymmärtää niitä. Ohjelmien luettavuus on tärkeää myös ohjelman kirjoittajalle itselleen. Kun ohjelma tehdään luettavaksi ja ymmärrettäväksi heti sen kirjoitushetellä, se auttaa selkeyttämään kirjoittajan ajatuksia, mikä edesauttaa laadukkaan ja vähemmän virheellisen ohjelman aikaansaamista. Tässä esitettävät tyylisäännöt pätevät C, C++, Java ja C# ohjelmointiin. Tässä esitettyjä tyylisääntöjä saa vapaasti käyttää vaikka tämän dokumentin Copyright on merkittykin Kari Laitisen nimiin. SISÄLTÖ: 1 Aaltosulut ja sisentäminen 2 2 Muuttujien, metodien (funktioiden), vakioiden yms. nimeäminen Luonnollisen nimeämisen periaate Muuttujien ja olioiden (olioviittausten) nimeäminen Metodien (funktioiden) nimeäminen Metodien formaalien paremetrien nimeäminen Vakioiden nimeäminen Tietotyyppien nimeäminen Sanojen erottaminen nimissä 4 3 Ohjelmatiedoston yleinen dokumentointi 5 4 Esimerkki ohjelmatiedoston alkukommenteista Tiedosto luotu Viimeisin muutos.

2 Ohjelmoinnin tyylisääntöjä Sivu 2 1 Aaltosulut ja sisentäminen Aseta aaltosulut siten että aaltosulkupari tulee alekkain samaan ohjelman sarakkeeseen kuin niihin liittyvä varattu sana, ja sisennä aaltosulkujen sisällä olevia käskylauseita kolme (tai neljä) välilyöntiä: if (... ) // yksi tai useampia sisennettyjä käskylauseita } while (... ) // yksi tai useampia sisennettyjä käskylauseita } Käytä aaltosulkuja silloinkin kun niiden sisässä on vain yksi käskylause. Tämä tekee ohjelman rakenteista yhdenmukaisia, ja vähentää virheitä kun ohjelmaa joudutaan muuttamaan. Älä käytä sisennyksessä ns. tabulointimerkkiä vaan tee sisennykset välilyöntimerkkejä käyttäen. Tästä seuraa se etu että katseletpa ohjelmaa millä välineellä tahansa, se todennäköisesti näkyy aina oikean näköisillä sisennyksillä. Useimmat ohjelmankirjoituseditorit (esim. Visual Studion editori, JCreatorin editori, Notepad++, Notepad2) voidaan konfiguroida siten että tabulaattoria painettaessa editori asettaa 3 tai 4 välilyöntiä ohjelmaan. Editori kannattaa aina konfiguroida tällaiseksi. 2 Muuttujien, metodien (funktioiden), vakioiden yms. nimeäminen 2.1 Luonnollisen nimeämisen periaate Oleellinen osa ohjelman kirjoittajan työtä on keksiä nimiä muuttujille, funktioille, vakioille, luokille, ja olioille. Nimeäminen on tärkeä seikka ohjelman ymmärrettäväksi tekemisessä. Nimeämisessä suositellaan käytettäväksi niin sanottua luonnollisen nimeämisen periaatetta, joka tarkoittaa että Nimissä ei käytetä perinteisiä lyhenteitä kuten i, j, ptr, len, buff, num, jne. Nimissä käytetään vain luonnollisen kielen sanoja ja nimet muodostetaan mieluiten useasta sanasta. Nimien muodostuksessa pyritään käyttämään luonnollisen kielen kielioppisääntöjä. Nimissä käytetty luonnollinen kieli voi olla joko suomi tai englanti. Ei ole oikein hyvää tyyliä sotkea useaa kieltä saman ohjelman nimiin. Seuraavissa esimerkeissä nimiä on annettu sekä suomeksi että englanniksi. Hyvien ja kuvaavien nimien miettiminen ohjelmia kirjoitettaessa on sikälikin hyvä asia, että se selkeyttää ohjelmoijan ajatuksia ja vähentää virheitä. Kun osaa antaa ohjelman elementeille (muuttujat, vakiot, tietotyypit, funktiot, jne.) hyvät luonnolliset nimet, se on osoitus myös siitä että on ymmärtänyt mitä ohjelman tulee tehdä. Toimivia ohjelmia ei voi kirjoittaa jos ei ymmärrä miten niiden pitäisi toimia.

3 Ohjelmoinnin tyylisääntöjä Sivu Muuttujien ja olioiden (olioviittausten) nimeäminen Muuttujien ja olioviittausten nimet kirjoitetaan pienillä kirjaimilla siten että ne ovat substantiivisia fraaseja. Seuraavassa muutama esimerkki muuttujien luonnollisista nimistä merkin_indeksi, luvun_indeksi, pallon_indeksi character_index, number_index, ball_index merkkien_maara_stringissa number_of_characters_in_string luku_nappaimistolta, annettu_luku integer_from_keyboard, given_integer Nimeämisessä on oleellista että nimissä käytetään useita sanoja. Esimerkiksi nimet annettu_luku tai luku_nappaimistolta kertovat paljon enemmän kuin pelkkä luku. Indeksimuuttujia tarvitaan yleensä kun viitataan taulukon johonkin paikkaan tai alkioon. Tällöin voidaan käyttää sellaista sääntöä, että indeksimuuttujan nimessä esiintyy sellainen sana joka kuvaa taulukossa olevia tietoelementtejä. Jos taulukkoon on talletettu merkkejä, tällöin hyvä indeksimuuttujan nimi on esim. character_index tai merkin_indeksi. Jos esim. graafisessa ohjelmoinnissa on käytössä taulukko jossa on Pallo-tyypisiä olioita, voidaan tällaista taulukkoa indeksoida muuttujalla jonka nimi on pallon_indeksi. 2.3 Metodien (funktioiden) nimeäminen Funktioiden ja metodien (jäsenfunktioiden) nimet kirjoitetaan siten että ne ovat imperatiivisia käskylauseita jotka alkavat verbillä. Seuraavassa muutama esimerkki tällaisista funktionimistä: etsi_stringia_tiedostosta search_string_in_file laske_keskiarvo calculate_mean_value talleta_oppilastaulukko_tiedostoon store_student_table_to_file 2.4 Metodien formaalien paremetrien nimeäminen Metodien formaaleilla parametreilla tarkoitetaan muuttuja- yms. määrittelyjä jotka annetaan metodin nimen perässä kaarisulkujen sisässä. Näiden nimeämisessä kannattaa käyttää sanoja annettu ja given seuraavaan tyyliin static int laske_keskiarvo( int[] annettu_lukutaulukko )... static int calculate_mean_value( int[] given_array_of_integers )... Formaalien parametrien nimissä voi tietysti käyttää myös sanoja kutsuja tai caller korostamaan sitä seikkaa että parametrin varsinainen arvo tulee metodin kutsujalta. Esim. em. nimet voisi sanoa näin lukutaulukko_kutsujalta ja array_of_integers_from_caller.

4 Ohjelmoinnin tyylisääntöjä Sivu Vakioiden nimeäminen Vakioilla tarkoitetaan ohjelmaelementtejä joille annetaan nimi mutta joita ei voi muuttaa ohjelman sen jälkeen kun niille on arvo annettu. On yleinen käytäntö ohjelmoinnissa, että muuttujien ja funktioiden nimet kirjoitetaan pienellä, mutta vakioiden nimet kirjoitetaan kokonaan suurilla kirjaimilla. Tätä käytäntöä kannattaa noudattaa Seuraavassa muutamia luonnollisilla nimillä varustettuja vakioita #define VIESTIPUSKURIN_KOKO 100 #define MESSAGE_BUFFER_SIZE 100 #define NUMBER_OF_ROWS_IN_USE 25 const int INITIAL_ARRAY_SIZE = 30 ; const float INCH_CONVERSION_CONSTANT = 2.54 ; 2.6 Tietotyyppien nimeäminen Tietotyyppien kuten luokkien nimet kirjoitetaan isoilla alkukirjaimilla. Näissä nimissä siis ensimmäinen kirjain on iso, mutta muut kirjaimet pieniä. Seuraavassa muutamia luonnollisia nimillä aloitettuja luokkamäärittelyjä: class Oppilas... class Date... class Bank_account Sanojen erottaminen nimissä Edellä olevissa esimerkkinimissä on sanat eroteltu toisistaan nimissä siten että sanojen välissä on käytetty alaviiva-merkkiä _. Erityisesti Java-ohjelmoinnissa on yleistä yhdistää nimen sanat siten että nimen keskellä oleva sana on kirjoitettu isolla, eikä alaviivaa (underscore) ole käytetty nimien erottimena. Tätäkin tapaa voidaan käyttää, kunhan muistetaan että muuttujien ja funktioiden nimissä on ensimmäinen kirjain aina pienellä ja vain tietotyyppien nimissä ensimmäinen kirjain on suurella. Vakikoiden nimissä, joissa kirjaimet ovat kaikki isoja, sanat on aina eroteltava alaviivaa käyttäen. Seuraavassa on esitetty nimiä vaihtoehtoisilla sanojen yhdistämistekniikkoilla luku_nappaimistolta integer_from_keyboard etsi_stringia_tiedostosta search_string_in_file Bank_account lukunappaimistolta integerfromkeyboard etsistringiatiedostosta searchstringinfile BankAccount

5 Ohjelmoinnin tyylisääntöjä Sivu 5 3 Ohjelmatiedoston yleinen dokumentointi 3.1 Ohjelmarivien pituus Ohjelmatiedoston kirjoituksessa on huomioitava että sen tulee näyttää samalta ruudulla ja paperilla. Ohjelman rivit on tehtävä niin lyhyiksi että ne eivät tulostuksessa katkeile. Ohjelmassahan saa lausetta jatkaa seuraavalla rivillä kunhan ei katkaise nimeä tai esim. stringivakiota. Suositus on että ohjelmarivit ovat maksimissaan 80-merkkisiä. Ohjelmia tulostettaessa paperille on käytettävä riittävän pientä tulostusfonttia jotta ohjelman rivit eivät katkeile. Tulostuksessa on käytettävä sellaista fonttia kuin Courier, jossa kaikki kirjaimet ovat yhtä leveitä. Kun tabulointimerkit eivät ole käytössä, ohjelman sisennykset näyttävät samalta eri editoreilla katsottuna, tai esim. opinnäytetyössä paperille tulostettuna. 3.2 Ohjelmatiedoston alkukommentit Lähdekielinen ohjelmatiedosto tulee kirjoittaa yhtä huolellisesti kuin mikä tahansa dokumentti jota kollegat joutuvat lukemaan. Hyvin dokumentoidun ohelman alusta tulee löytyä ainakin seuraava informaatio kommentteina: Ohjelman tuottanut organisaatio (esim. OAMK Tekniikan yksikkö) Ohjelman kirjoittajien nimet Ohjelman nimi, joka toimii dokumentin otsikkona (esim.. Dokumentin tyyppi (esim. C++ -kielinen lähdeohjelma tai Java-kielinen lähdeohjelma) Ohjelmatiedoston nimi Ohjelman versiohistoria, jossa kerrotaan versionumerot, tehdyt muutokset, ja ohjelman muuttajien nimet. Versiohistoriaan voidaan laittaa myös merkinnät jos ohjelma on hyväksytty virallisesti katselmointikokouksessa. Versionumerointi voidaan aloittaa siten että versio 0.0 syntyy silloin kun ohjelmatiedosto luodaan ja ohjelmaa ryhdytään kirjoittamaan. Näin tiedetään milloin ohjelmointityö on aloitettu. Kääntämis- ja käyttöönotto-ohjeet, joista ilmenee millä kääntäjällä ohjelma voidaan kääntää ja mitä muuta oleellista liittyy ohjelman toimintaan saattamiseksi. Seuraavassa kohdassa on esimerkin avulla näytetty kuinka em. informaatio voidaan laittaa ohjelmatiedoston alkuun.

6 Ohjelmoinnin tyylisääntöjä Sivu 6 4 Esimerkki ohjelmatiedoston alkukommenteista Tällä ja seuraavalla sivulla esitetään ohjelmatiedoston oppilaat_oo.cpp alku. Ohjelmatiedoston alkuun voidaan luoda tällainen kansilehti, joka kuvaa yleisellä tasolla dokumentin luonteen. Kansilehden oikeassa yläkulmassa kerrotaan minkä tyyppisestä dokumentista on kysymys. Lähdekieliset ohjelmatkin ovat siis dokumentteja. /* OAMK / Tekniikan yksikko Kari Laitinen C++ kielinen lahdeohjelma OPETTAJAN APUOHJELMA Tiedostonimi: oppilaat_oo.cpp Versio: 0.1 Versiohistoria: VERSIO PVM MUUTTAJA KOMMENTTI K Laitinen Tiedosto luotu K Laitinen Viimeisin muutos */ Jokaisella dokumentilla on oma versiohistoriansa. Jonain päivänä dokumentin tiedosto luodaan, jonain päivänä sitä on viimeksi muutettu. Tällaiset asiat voidaan kertoa versiohistoriassa. Versiohistoriaan merkitään myös kun dokumentti hyväksytään virallisesti esim. katselmoinnissa. oppilaat_oo.cpp - 1: Ohjelmatiedoston aloittava ohjelman "kansilehti".

7 Ohjelmoinnin tyylisääntöjä Sivu 7 /* OHJELMAN KUVAUS JA KÄYTTÖOHJEET Tama ohjelma on oliosuuntautunut versio C-kielen opiskelumateriaalin ohjelmasta oppilaat.cpp. Tama tiedosto sisaltaa ohjelman jonka avulla opettaja voi pitaa jarjestyksessa oppilaisiinsa liittyvia tietoja. Ohjelmaa kaytetaa komentorivipohjaisesti nappailemalla "oppilaat_oo" komentorivilta esim. MS-DOS ikkunassa. Ohjelma toimii kuten oppilaat.cpp mutta tahan on lisatty ominaisuus etta opiskelijoiden tiedot voi tallettaa tekstitiedostoon, jota voi kasitella esim. editoreilla. Lisaksi funktio nayta_yhden_opiskelijan_tiedot kayttaa funktiota strstr tietojen etsintaan. Nain tiedot loytyvat myos epataydellisesti annetun nimen perusteella */ /* OHJELMAN KÄÄNTÄMINEN Ohjelma kaantyy ainakin seuraavilla kaantajilla: Borland C Microsoft 32-bit C/C++ Optimizing Compiler v */ oppilaat_oo.cpp - 2. Ohjelman käyttöohjeet ja käännösohjeet.