Koodauskäytänteet Ohjelmointi 1 -kurssilla

Tämä ohje on tarkoitettu tueksi tehtävien ja harjoitustyön tekoon Ohjelmointi 1 -kurssilla. Esimerkiksi harjoitustyössä arvioidaan koodin laatua nimeämisen, sisennyksen ja dokumentoinnin kannalta.

Nämä ohjeet pohjautuvat virallisiin C#-koodauskäytänteisiin. Tilan säästämiseksi tarkempia perusteluja on jätetty pois. Epäselvissä tapauksissa tai perusteluja löydät kielen viralliset koodauskäytänteet Microsoft Learn -palvelusta:

Nimeäminen

Hyvin valitut nimet tekevät koodista itseään selittävää. Vältä skandinaavisia merkkejä (ä, ö, å) ja käytä kuvaavia nimiä.

Luokat ja tiedostot

Luokan nimen tulee täsmätä lähdekooditiedoston nimen kanssa. Esimerkiksi luokka Pallo tallennetaan tiedostoon Pallo.cs.
Luokkien nimet kirjoitetaan PascalCase-tyylillä, eli jokainen sana alkaa isolla kirjaimella ilman välilyöntejä.
- Oikein: Pallo, PelinPaaikkuna, Pisteytyslaskuri
- Väärin: pallo, pelinPaaikkuna, pisteytyslaskuri

Muuttujat ja parametrit

Paikalliset muuttujat, aliohjelmien parametrit ja luokan attribuutit kirjoitetaan camelCase-tyylillä. Ensimmäinen sana alkaa pienellä ja seuraavat isolla.
Yksityisten luokkamuuttujien (attribuuttien) eteen lisätään alaviiva _.
- Oikein: pelaajanNimi, pisteidenMaara, _leveys
- Väärin: PelaajanNimi, pisteiden_maara, Leveys

Alla vielä koostava esimerkki koodista, jossa osat on nimetty oikealla tyylillä:

public class Pelaaja
{
    // Yksityinen attribuutti alaviivalla ja camelCasella
    private string _nimi;
    private int _pisteet;

    public void AsetaPisteet(int uudetPisteet) // Parametri camelCasella
    {
        int bonusPisteet = 10; // Paikallinen muuttuja camelCasella
        _pisteet = uudetPisteet + bonusPisteet;
    }
}

Vakiot

Vakiot (const) kirjoitetaan PascalCase-tyylillä.
- Oikein: const int MaksimiPelaajamaara = 4;
- Hyväksytään historiallisista syistä: const int MAKSIMI_PELAAJAMAARA = 4;
- Väärin: const int maksimiPelaajamaara = 4;

Aliohjelmat

Aliohjelmien nimet kirjoitetaan PascalCase-tyylillä.
- Oikein: LaskePisteet(), PiirraPallo()
- Väärin: laskePisteet(), piirra_pallo()

Koodin asettelu

Koodin asettelu vaikuttaa merkittävästi sen luettavuuteen.

Aaltosulut ja sisennykset

Aloittava aaltosulku { tulee aina omalle rivilleen.
Lopettava aaltosulku } tulee omalle rivilleen ja samalle tasolle kuin vastaava aloittava sulku.
Sisennykseen käytetään aina neljää (4) välilyöntiä. Älä käytä tabulaattoria.

Välilyönnit

Aliohjelman nimen ja aloittavan sulun ( väliin ei tule välilyöntiä.
Kontrollirakenteiden (kuten if, while, for) avainsanan ja ehdon sulkujen väliin tulee välilyönti.
- Oikein: LaskeYhteenveto(pisteet); ja if (pelaaja.OnVoittanut())
- Väärin: LaskeYhteenveto (pisteet); ja if(pelaaja.OnVoittanut())

Tyhjät rivit

Aliohjelmien väliin jätetään kaksi tyhjää riviä.
Käytä yhtä tyhjää riviä erottamaan loogisia osia aliohjelman sisällä. Älä kuitenkaan käytä useita tyhjiä rivejä peräkkäin.

Koostava esimerkki oikeasta asettelusta:

public class Esimerkki
{
    public static void Main(string[] args)
    {
        for (int i = 0; i < 5; i++)
        {
            Console.WriteLine("Selkeästi sisennetty!");
        }
    }


    public static int Summa(int summattava1, int summattava2)
    {
        return summattava1 + summattava2;
    }
}

Dokumentointi

Hyvä dokumentaatio auttaa ymmärtämään, mitä koodi tekee.

Kaikki luokat, aliohjelmat ja attribuutit tulee dokumentoida XML-kommenteilla (///).
Lisää tiedoston alkuun tekijän nimi ja versiotiedot.

Esimerkki hyvin dokumentoidusta koodista:

/// @author Maija Meikäläinen
/// @version 1.0
/// <summary>
/// Luokka, joka vastaa pelin logiikasta.
/// </summary>
public class PeliLogiikka
{
    /// <summary>
    /// Attribuutti, joka vastaa asiasta X...
    /// </summary>
    private double attribuutti = 2.0;

    /// <summary>
    /// Laskee kahden luvun summan ja palauttaa tuloksen.
    /// </summary>
    /// <param name="luku1">Ensimmäinen luku.</param>
    /// <param name="luku2">Toinen luku.</param>
    /// <returns>Lukujen summa.</returns>
    public int LaskeSumma(int luku1, int luku2)
    {
        return luku1 + luku2;
    }
}