Tässä dokumentissa kuvataan Keimo-projektissa sovellettavia ohjelmointikäytäntöjä. Päivämäärä Projektiryhmä Keimo

Transkriptio

1 T Tietojenkäsittelyopin ohjelmatyö Sisältö Tässä dokumentissa kuvataan Keimo-projektissa sovellettavia ohjelmointikäytäntöjä. Päivämäärä Projektiryhmä Keimo Kirjoittajat Iiro Ojala Muutokset PVM Tekijä Versio Selitys Iiro Ojala 0.1 Alustava versio Iiro Ojala 0.2 Versio sisäiseen katselmointiin Iiro Ojala 0.3 Katselmoinnissa päätetyt muutokset Iiro Ojala 1.0 Palautukseen valmis versio 1

2 Sisällysluettelo 1 Johdanto Nimeämiskäytännöt Luokat Funktiot Yleiset funktiot Aksessorit (setterit ja getterit) Muuttujat Paikalliset muuttujat Osoitinmuuttujat Viittausmuuttujat Vakiomuuttujat Jäsenmuuttujat Staattiset jäsenmuuttujat Globaalit muuttujat Enumeraatiot Tyyliohjeita Välilyöntien käyttö Tabulaattorin leveys Rivin katkaiseminen Aaltosulkeiden sijoittelu Aaltosulkeiden käyttö yksirivisissä lohkoissa Joitakin C++-ohjelmointikäytäntöjä Kopiokonstruktori ja sijoitusoperaattori Virtuaalifunktiot #define direktiivi const määre C -Structit Ystäväluokat Ystäväfunktiot Yksityinen perintä Moniperintä Lähdekooditiedostot C++-luokan esimerkkimäärittely

3 1 Johdanto Dokumentissa kuvataan Keimo-projektissa sovellettava ohjelmointityyli sekä joitakin ohjelmointikäytäntöjä. Yhteisten sääntöjen tarkoitus on helpottaa koodin luettavuutta ja siten nopeuttaa ohjelman jatkokehitystä ja ylläpitöa. Dokumenttia täydennetään projektin kuluessa aina tarpeen niin vaatiessa. Kaikkien ohjelmoijien tulee noudattaa dokumentissa esitettyjä sääntöjä. Tyylin noudattamista kontrolloidaan koodikatselmuksissa, joissa tämä dokumentti toimii tyylitarkistuslistana. Ohjeen nimeämiskäytäntöjä ja yleisiä tyyliohjeita koskevia lukuja 2 ja 3 sovelletaan projektissa sellaisenaan C++-kieliseen ja soveltuvilta osin Javakieliseen ohjelmointiin. Joitakin tärkeitä vain C++-kielistä ohjelmointia koskevia käytäntöjä on kirjattu lukuun 3. 2 Nimeämiskäytännöt 2.1 Luokat Luokan nimi kirjoitetaan isolla alkukirjaimella. Alaviivoja ei käytetä ja sanavälit ilmoitetaan isolla alkukirjaimella. class CameraManager ; 2.2 Funktiot Yleiset funktiot Funkton nimi kirjoitetaan pienellä alkukirjaimella. Alaviivoja ei käytetä ja sanavälit ilmoitetaan isolla alkukirjaimella. Paluuarvon tietotyyppiä ei ilmoiteta funktion nimessä. calculaterotationangle(); Aksessorit (setterit ja getterit) 3

4 Aksessori nimetään kuten yleinen funktio ja sen nimi noudattaa yksinkertaista kaavaa: Attribuutin arvon asettavan jäsenfunktion nimi on muotoa set + attribuutin nimi. Attribuutin arvon palauttavan funktion nimi on muotoa get + attribuutin nimi, tai mikäli attribuutti (ja funktion paluuarvo) on totuusarvotyyppinen, is + attribuutin nimi. bool setrotationangle( angle); getrotationangle(void); isvalid(); 2.3 Muuttujat Paikalliset muuttujat Paikallisen muuttujan nimi kirjoitetaan pienellä alkukirjaimella. Alaviivoja ei käytetä ja sanavälit ilmoitetaan isolla alkukirjaimella. Muuttujan tietotyyppiä ei ilmoiteta muuttujan nimessä. int index = 0; rotationangle = 0.0; Osoitinmuuttujat Osoitinmuuttuja nimetään kuten paikallinen muuttuja ja sen nimen alkuun lisätään pieni p jokaista osoitintasoa kohden. Kirjainta seuraava sana kirjoitetaan isolla alkukirjaimella. int *pindex; **pprotationangle; Viittausmuuttujat Viittausmuuttuja nimetään kuten paikallinen muuttuja ja sen nimen alkuun lisätään pieni r. Kirjainta seuraava sana kirjoitetaan isolla alkukirjaimella. int &rindex; &rrotationangle; Vakiomuuttujat 4

5 Vakiomuuttujan koko nimi kirjoitetaan isoilla kirjaimilla ja sanaväli ilmoitetaan alaviivalla. const int MAX_ROUNDS = 255; Jäsenmuuttujat Jäsenmuuttuja nimetään kuten paikallinen muuttuja ja sen nimen alkuun lisätään liite m_. Liittettä seuraa pieni kirjain. int m_index; *m_protationangle; Staattiset jäsenmuuttujat Staattinen jäsenmuuttuja nimetään kuten paikallinen muuttuja ja sen nimen alkuun lisätään m_-liitteen sijasta liite s_. Liittettä seuraa pieni kirjain. static int s_referencecount; Globaalit muuttujat Globaali muuttuja nimetään kuten paikallinen muuttuja ja sen nimen alkuun lisätään liite g_. Liittettä seuraa pieni kirjain. Globaalien muuttujien näkyvyyttä rajoitetaan aina static-määreellä. static int g_isconnectionalive; 2.4 Enumeraatiot Enumeraation tyyppinimi kirjoitetaan isolla alkukirjaimella. Alaviivoja ei käytetä ja sanavälit ilmoitetaan isolla alkukirjaimella. Enumeraation nimetyt arvot kirjoitetaan kokonaan isoilla kirjaimilla ja sanaväli ilmoitetaan alaviivalla. Julkisten enumeraatioiden nimetyissä arvoissa pitää käyttää kirjaston tai packagen nimestä johdettua etuliitettä, paikallisten ei. enum ObjectState RND_OBJECT_NOT_FOUND, RND_OBJECT_LOADED, RND_OBJECT_NOT_LOADED, 5

6 enum ColorType COLOR, BLACK_AND_WHITE 3 Tyyliohjeita 3.1 Välilyöntien käyttö Välilyöntiä käytetään erottamaan kaikkia moniargumenttisia operaattoreita argumenteistaan. Kuitenkin Pilkkua ennen ei tule ja sen jälkeen tulee välilyöti. Välilyöntiä ei käytetä erottamaan yksiargumettisia operaattoreita argumentistaan, eikä esimerkiksi indeksiä indeksointioperaattorista. Välilyöntiä ei yleensä käytetä ennen eikä jälkeen kaarisulkua, ellei sen käyttöä kulloinkin kyseessäolevaan tilanteeseen ole erikseen määritelty. 3.2 Tabulaattorin leveys Sisennyksessä käytettävä tabulaattorin leveys on neljä merkkiä. Sisennykset kirjoitetaan tiedostoon tab-merkkeinä(ei konvertoida välilyönneiksi). 3.3 Rivin katkaiseminen Rivi katkaistaan aina moniargumenttisen operaattorimerkin jälkeen ja operaattorin argumentit sisennetään aina samalle tasolle. Yksiargumenttisia operaattoireita ei koskaan eroteta argumentistaan. if(((count + offset) >= (limiters + offset * *plength)) && isvalid()) Aaltosulkeiden sijoittelu Aaltosulje kirjoitetaan C++-koodissa aina omalle rivilleen. Lohkon aloittava sulje tulee edellisen rivin kanssa samalle tasolle ja lohkon koodi sisennetään yhden 6

7 tabulaattorin verran. Lohkon päättävä sulje tulee samalle tasolle lohkon avaavan sulun kanssa. Kyseessä on siis Allman/BSD nimellä tunnettu tyyli. Java-koodissa noudatetaan pääsääntöisesti Sunin julkaisemia Javatyyliohjeita. Ohjeet eivät ota otaa kantaa aaltosulkeiden sijoitteluun, mutta kaikki Sunin toimittama esimerkkimateriaali on muotoiltu noudattaen K&R/One True Brace tyyliä. Tyylin mukaan lohkon avaavan sulkeen paikka on edellisen rivin lopussa. Projektin Java-koodissa voidaan käyttää kumpaa tahansa mainituista tyyleistä, mutta valittua tyyliä tulee käyttää yhtenäisesti koko laadittavassa modulissa. bool validate(void)... boolean validate() Aaltosulkeiden käyttö yksirivisissä lohkoissa Yksirivisten lohkojen ympärillä ei normaalisti käytetä aaltosulkeita. Poikkeuksena tähän on if else if else lause, jossa kaikkien lohkojen ympärillä käytetään sulkeita, mikäli yksikin lohkoista on monirivinen. Aaltosulkuja harkittaessa moniriviseksi katsotaan myös rivi, joka on muotoilu syistä katkaistu useammalle kuin yhdelle riville. if(m_isvalid) m_index++; else validator->validate(this); if(m_isvalid) m_index++; else validator->validate(this); m_index++; m_isvalid = true; while(isvalid()) applyparameters(index, lengtharray); 7

8 4 Joitakin C++-ohjelmointikäytäntöjä 4.1 Kopiokonstruktori ja sijoitusoperaattori Jokaiselle luokalle tulee määritellä kopiokonstruktori ja sijoitusoperaattori(=operaattori). Mikäli luokasta ei ole tarkoitus muodostaa kopioita, tai toiminnallisuutta ei vielä tarvita ja se siksi jätetään toteuttamatta, kopiokonstruktori ja sijoitusoperaattori määritellään yksityisiksi. 4.2 Virtuaalifunktiot Mikäli aliluokka korvaa yläluokkansa virtuaalifunktion, tulee funktio merkitä virtuaaliseksi myös aliluokan määrittelyssä. Yksityisten jäsenfunktioiden ei tulisi koskaan olla virtuaalisia. 4.3 #define direktiivi #define direktiivillä ei tule määritellä toiminnallisia makroja eikä symbolisia vakioita. Näiden sijasta tulee käyttää inline funktioita ja vakiomuuttujia. Sen sijaan #define:a tulee käyttää estämään saman headerin sisällyttäminen useamman kuin yhden kerran yhteen käännösyksikköön. 4.4 const määre Kaikki luokkien vakiofunktiot tulee merkitä const-funktioiksi. Mikäli luokan jäsenfunktiota ei ole merkitty const:ksi, se oletusarvoisesti mutatoi luokan tietoja. Myös kaikki funktioiden osoitin- ja viittausarvoiset vakioparametrit tulee merkitä const:ksi. Jos osoitin tai viittaus ei ole const, funktio oletusarvoisesti muuttaa sen sisältöä. Tämä on erityisen tärkeää julkisissa rajapinnoissa. 4.5 C -Structit C-tyylisiä structeja voi käyttää niille sopivissa paikoissa. Structeissa ei saa käyttää jäsenfunktioita, perintää, eikä muita kuin julkisia ei staattisia jäsenmuuttujia. Myöskään m_ -liitettä ei käytetä structin jäsenmuuttujien nimissä. Mikäli näitä ominaisuuksia tarvitaan, tulee toiminnallisuus kirjoittaa luokan muotoon. struct Point3d 8

9 ; x; y; z; 4.6 Ystäväluokat Ystäväluokkien käyttöä tulee välttää. Yleensä niiden sijasta tulee käyttää julkisia aksessoreja ja tarvittaessa ystäväfunktioita. 4.7 Ystäväfunktiot Ystäväfunktioita tulee käyttää harkiten. Luokan ulkopuoliset itsenäiset ystäväfunktiot esitellään vain luokan esittelyn yhteydessä ja niiden toteutus kirjoitetaan luokan toteutuksen kanssa samaan tiedostoon. Luokan ystävä- ja toisen luokan jäsenfunktiota ei yleensä tule käyttää julkisissa rajapinnoissa. Perustellusta syystä niitä voi käyttää komponenttien sisäisissä toteutuksissa. 4.8 Yksityinen perintä Yksityistä perintää tulee välttää. Normaalisti sen sijasta voi käyttää joko kompositiota tai julkista perintää. 4.9 Moniperintä Kompleksisten luokkien moniperintää tulee käyttää erittäin harkiten. Virtuaalista perintää tulee käyttää aina, jos ilman sitä tuloksena olisi ns. timanttihierarkkia. Moniperintää voi käyttää Javan interfaceja vastaavan toiminnallisuuden aikaansaamiseksi Lähdekooditiedostot Tiedostonimen pääte valitaan seuraavasti: Tyyppi Pääte C++-lähdekoodi.cpp C++-header.hpp C-lähdekoodi.c C-header.h 9

10 5 C++-luokan esimerkkimäärittely class String public: String(); String(const char *pchars); ~String(); private: String(const String &rstring); String &operator=(const String &); ; // to be continued... 10