wiki:CsKoodausKaytanteet
Last modified 8 months ago Last modified on 2016-10-30 09:42:36

Dokumentti siirretty TIMiin


Ohjelmointi 1 kurssin koodauskäytänteet

Ensisijaisesti tällä kurssilla pyritään käyttämään C#-koodauksessa tyypillisiä käytänteitä, jotka löytyvät tästä linkistä. 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: Autoja jäljellä
Muuttujan nimenä oikein: autojaJaljella
Väärin: autoja_jaljella, autojajaljella,
        Autoja_Jäljellä, AutojaJäljellä,
        AutojaJaljella, ...

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

3. Vakiot

Tällä kurssilla vakiot kirjoitetaan suuraakkosin siten, että sanat erotetaan alaviivalla (_). Näin ne erottaa helposti muuttujien nimistä, jotka alkavat pienellä kirjaimella.

Esimerkki:

const int KUUKAUSIEN_LKM = 12;

4. 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, ...

5. 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)  

6. 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
{
// ...

7. 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> // yksikkötesti Comtestin avulla
    /// <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>
    /// </example>
    public static int MontakoVapaata(int[,] ruudut) // funktio alkaa isolla, parametri pienellä
    {
        int vapaita = 0; // lokaali muuttuja, aloitetaan pienellä
        foreach (int arvo in ruudut)
        {
            if (arvo == 0) vapaita++; // if:n jälkeen ja == ympärillä tyhjät, sulun jälkeen myös
        }

        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);
    }
}

8. String vai string

Maailmalla suositus tuntuu olevan että muuttujat esitellään string ja kun kutsutaan staattista metodia, niin String eli

    public static void Main(string[] args)
    {
        string jono = "kissa";
        int i = jono.IndexOf('s');
        string tulostettava = String.Format("Paikka oli {0}", i);
        Console.WriteLine(tulostettava);
    }

Linkkejä

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

Muita:

Nimeämisestä yleisesti