1. Ohjelmointi 1 kurssin koodauskäytänteet
    1. 1. Tiedostot ja luokat
    2. 2. Muuttujat
    3. 3. Aliohjelmat, funktiot ja metodit
    4. 4. Sulut ja välilyönnit ja tyhjät rivit
    5. 5. Kommentointi
    6. 6. Saantimääreet
    7. Esimerkki
    8. Linkkejä
    9. Nimeämisestä yleisesti
Pages linking to CsKoodausKaytanteet:
s2011/ht-palautusohjeet-cs
s2011
k2012/ht-palautusohjeet-cs
k2012
s2012/ht-palautusohjeet-cs
s2012

Ohjelmointi 1 kurssin koodauskäytänteet

  • ensisijaisesti pyritään käyttämään C#-koodauksessa tyypillisiä käytänteitä
  • seuraavassa joitakin pääkohtia, tarkemmin asiasta löytää alla olevista linkeistä

1. Tiedostot ja luokat

  • tiedoston nimi sama kuin luokan nimi, tällöin DoxyGen (http://www.stack.nl/~dimitri/doxygen/) dokumentin teko onnistuu ilman kikkailuja
  • luokan nimi alkaa aina isolla kirjaimella (ja siis myös tiedoston, esim. class Laivanupotus on tiedostossa Laivanupotus.cs)
  • Esimerkkejä luokkien nimistä: 
Suomeksi: Laiva
Luokan nimenä oikein: Laiva
Väärin: laiva, LAIVA

Suomeksi: Sierpinskin kolmio
Luokan nimenä oikein: SierpinskinKolmio
Väärin: sierpinskinkolmio, sierpinskinKolmio, Sierpinskinkolmio, 
        Sierpinskin_Kolmio, SIERPINSKIN_KOLMIO, SIERPINSKINKOLMIO

2. Muuttujat

  • lokaalit muuttujat (myös parametrit) alkaa pienellä kirjaimella
  • attribuutit alkavat pienillä kirjaimilla
  • sanavälit osoitetaan vaihtamalla kirjain isoksi 

Suomeksi: Pituus
Muuttujan nimenä oikein: pituus, l (niinkuin length)
Väärin: Pituus, PITUUS, p (liian monitulkintainen)

Suomeksi: Ammuksia jäljellä
Muuttujan nimenä oikein: ammuksiaJaljella
Väärin: ammuksia_jaljella, ammuksiajaljella,
        Ammuksia_Jäljellä, AmmuksiaJäljellä,
        AmmuksiaJaljella, ...

Suomeksi: Elämälaskuri
Muuttujan nimenä oikein: elamalaskuri
Väärin: Elamalaskuri, ElamaLaskuri, elämälaskuri,
        elämä_laskuri, ...

3. Aliohjelmat, funktiot ja metodit

  • aliohjelmien, funktioiden ja metodien nimet alkavat isolla kirjaimella 
Suomeksi: Piirrä kolmio
Aliohjelman nimenä oikein: PiirraKolmio
Väärin: piirraKolmio, piirräKolmio,
        PiirräKolmio, Piirrä_Kolmio,
        piirrä_kolmio, ...

4. Sulut ja välilyönnit ja tyhjät rivit

  • aliohjelmien jälkeen kaksi tyhjää riviä
  • tyhjä rivi kun asiayhteys muuttuu
  • aloittava lohkosulku { omalla rivillään
  • lopettava lohkosulku } samassa sarakkeessa aloittavan lohkosulun kanssa
  • sisennyksessä käytettään välilyöntejä, 4/sisennystaso, ei TAB-merkkiä (erikoismerkit näet esim. Context-ohjelmassa View --> Show special characters, tai Notepad++:ssa View --> Show symbol --> Show all characters)
  • aliohjelmakutsuissa aloittava kaarisulku ( kirjoitetaan kiinni funktion nimeen: 
MontakoVapaata(ruudut);  // VÄÄRIN olisi: MontakoVapaata (ruudut);
  • kontrollirakenteiden ehdoissa aloittava kaarisulku ( kirjoitetaan irti kontrollirakenteen avainsanasta: 
if (arvo == 0)      // VÄÄRIN olisivat if(arvo == 0), tai if( arvo == 0 )
while (summa < 100) // VÄÄRIN olisi: while(summa < 100)

5. Kommentointi

  • käytetään XML-kommentointia jotta saadaan dokumentaatio
  • mielellään testataan kaikki kohtuuvaivalla testattavissa olevat funktiot
  • tekijä- ja versiotieto tiedoston alkuun, esimerkiksi 
using System;
using System.Collections.Generic;

/// @author  Antti-Jussi Lakanen, Martti Hyvönen
/// @version 22.12.2011
///
/// <summary>
/// Harjoitellaan vielä taulukoiden käyttöä.
/// </summary>
public class Arvosana
{
// ...

6. Saantimääreet

  • kirjoitetaan näkyville kaikki saantimääreet, vaikka ne ovatkin oletuksena käyttökelpoisia.
    • siis attribuuteille private
    • metodeille private/protected/public sen mukaan mikä on tarkoituksenmukaista

Esimerkki

using System;

/// @author  Vesa Lappalainen
/// @version 22.12.2011

/// <summary>
/// Laivanupotuspeli.
/// </summary>
public class Laivanupotus // Luokan nimi, siksi alkaa isolla
{ // aloittava sulku omalla rivillä
    private int laivojenMaara = 4;  // attribuutti, siksi alkaa pienellä, kirjoitetaan private

    /// <summary>
    /// Lasketaan montako vapaata ruutua on jäljellä
    /// </summary>
    /// <param name="ruudut">taulukko ruuduista, kussakin 
    /// ruudussa 0 = vapaa, muu numero = laivan numero.</param>
    /// <returns>vapaiden ruutujen määrän</returns>
    /// @example // nykytapojen mukaista on testata funktiot
    /// <pre name="test">
    ///    int[,] ruudut = {{1, 0, 2}, {0, 0, 3}};
    ///    Laivanupotus.MontakoVapaata(ruudut) === 3;
    ///    int[,] ruudut0 = {{1, 4, 2}, {5, 5, 3}};
    ///    Laivanupotus.MontakoVapaata(ruudut0) === 0;
    /// </pre>
    /// @endexample
    public static int MontakoVapaata(int[,] ruudut) // funktion nimi, alkaa isolla, paikat parametri, alkaa pienellä
    {
        int vapaita = 0; // lokaali muuttuja, aloitetaan pienellä
        foreach (int arvo in ruudut)
        {
            if (arvo == 0) vapaita++; // tyhjä if-jälkeen, == merkit ympärillä tyhjät, sulun jälkeen tyhjä
        }

        return vapaita;
    } // loppusulku samassa sarakkeessa alkusulun kanssa, kaksi tyhjää riviä funktion jälkeen


    /// <summary>
    /// Lasketaan montako vapaata ruutua jäljellä
    /// </summary>
    /// <param name="args">ei käytössä</param>
    /// 
    public static void Main(string[] args)
    {
        int[,] ruudut = new int[10, 10];
        ruudut[3, 3] = 1;

        int vapaita = MontakoVapaata(ruudut); // funktiokutsussa sulku kiinni funktion nimessä

        System.Console.WriteLine("Vapaita " + vapaita);
    }
}

Linkkejä

Päälinkki: http://msdn.microsoft.com/en-us/library/ms184410.aspx

Muita:

Nimeämisestä yleisesti