koodin_laatuvaatimukset.md

Koodin laatuvaatimukset

Kurssin tavoitteena on, että tuotoksesi voisi ottaa kuka tahansa kaverisi tai muu opiskelija ylläpidettäväksi ja laajennettavaksi. Tavoitteena on Clean code - selkeää, ylläpidettävää ja toimivaksi testattua koodia. Tämä sivu esittelee erityisesti lopullisen palautuksen laatuvaatimukset, mutta lueteltuja vaatimuksia on hyvä noudattaa mahdollisimman pian.

Clean Code

Alla luetellaan Clean Code -periaatteita noudattavan koodin laatuvaatimukset. Ohjelmoinnin harjoitustyön tulisi noudattaa periaatteita mahdollisimman hyvin.

1. Nimeä luokat, metodit, attribuutit, parametrit ja muuttujat selkeästi ja johdonmukaisesti

• Käytä mahdollisimman kuvaavia nimiä kaikkialla
  • Luokkien nimet aina isolla alkukirjaimella
• Metodit, attribuutit, parametrit ja muuttujat aina camelCase
• Muuttujat, joilla on iso käyttöalue, tulee olla erittäin selkeästi nimettyjä.
• Lyhyen metodin sisäisille muuttujille riittää yleensä lyhyempi nimi.
• Jos metodia käytetään vähän, tulee nimen olla mahdollisimman kuvaava.
• Tee nimentä englanniksi.

Huomaa: tee uudelleennimeäminen NetBeansin Refactor/rename-ominaisuuden avulla, ks kohta refaktorointi

2. Ei pitkiä metodeja

• Sovelluslogiikan metodin pituuden tulee ilman erittäin hyvää syytä olla korkeintaan 20 riviä.
• Pitkät metodit tulee jakaa useampiin metodeihin.
• Yksi metodi - yksi pieni tehtävä. (Single Responsibility)
  • Helpottaa myös testaamista

3. Ei copy-pastea

• Toistuvan koodin saa lähes aina hävitettyä
• Tapauksesta riippuen luo metodi tai yliluokka, joka sisältää toistuvan koodin

4. Luokkien Single Responsibility

• Luokkien tulisi hoitaa vain yhtä asiaa
• Erityisen tärkeää on erottaa käyttöliittymä ja sovelluslogiikka
  • Kaikki tulostaminen tulisi tapahtua käyttöliittymässä
  • Sovelluslogiikkaan liittyviä operaatioita ei tehdä käyttöliittymässä
• Toisaalta tiettyä asiaa ei pidä hoitaa useissa eri luokissa
• Esimerkiksi tiedoston lukemista tai -kirjoittamista EI tulisi löytyä useasta luokasta
  • Tee oma luokka tiedostojen käsittelylle

5. Pakkaukset

• << Default package >> EI saa olla käytössä
• Luokat tulee jakaa pakkauksiin
• Pakkausten nimet aina pienellä (lowercase)
• Kaikkien pakkausten tulee olla yhden juuripakkauksen alla, esim. fi.omanimi
• Sovelluslogiikkapakkaus olisi näin tehtynä siis fi.omanimi.logics, käyttöliittymä fi.omanimi.gui
• Yhdessä pakkauksessa yksi kokonaisuus
• Esim. yhdessä pakkauksessa käyttäjätileihin liittyvät luokat
• Toisessa muu logiikka
• Kolmannessa käyttöliittymän luokat
• jne.
• Myös testipakkausten nimentä tulee olla oikea, ks. 6. Testaus

6. Testaus

• Generoidut testit ovat kiellettyjä
  • Tarkoitus on oppia testaamaan itse oma ohjelmakoodinsa
  • Generoidut testit harvoin testaavat mitään hyödyllistä
  • Generoitujen testien tai testipohjien käyttö: 0 pistettä
• Automatisoitu yksikkötestaus (=JUnit -testit) on pakollista
  • Testauksen puutteessa kurssisuoritus hylätään
• Palauta mieleesi Ohjelmistotekniikan Menetelmien testaustehtävät:
  • Testaa mahdollisimman montaa luokkaa
  • Testaa mahdollisimman montaa metodia
  • Testaa rajatapauksia
  • Testaa virheellis