Ohjelmointi 1 -kurssin ohjelmointikäytänteet

Ensisijaisesti tällä kurssilla pyritään käyttämään C#-ohjelmoinnin tyypillisiä käytänteitä. Seuraavassa joitakin pääkohtia, tarkemmin asiasta löytää alla olevista linkeistä.

1. Nimeäminen

1.1 Luokat ja tiedostot

• Tiedoston nimi sama kuin luokan nimi.
• Luokan nimi alkaa aina isolla kirjaimella, ja siten myös tiedoston nimi. Esimerkiksi class Laivanupotus kirjoitetaan tiedostoon, jonka nimi on 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

1.2 Muuttujat

• Paikalliset muuttujat (myös parametrit) aloitetaan pienellä kirjaimella.
• Attribuutit alkavat pienillä kirjaimilla.
• Sanavälit osoitetaan vaihtamalla seuraavan sanan alkukirjain isoksi (camelCase).

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

Alkaen keväästä 2024: yksityisten luokkamuuttujien eteen merkitään alaviiva, esim

private int _elamat = 3;

1.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:

Keväästä 2024 alkaen vakiot kirjoitetaan PascalCase-tyylillä, esim.

public const int Kuukausia = 12;
public const int KandiTutkintoOpintopisteina = 180;

1.4 Aliohjelmat, funktiot ja metodit

Aliohjelmien, funktioiden ja metodien nimet alkavat isolla kirjaimella (PascalCase)

Suomeksi: Piirrä kolmio
Aliohjelman nimenä oikein: PiirraKolmio
Väärin: piirraKolmio, piirräKolmio,
        PiirräKolmio, Piirrä_Kolmio,
        piirrä_kolmio, ...

1.5 Huomautus skandien käytöstä

Vältä skandien (å, ä, ö) käyttöä. Vaikka periaatteessa skandeja on mahdollista käyttää muuttujien, luokkien, tiedostojen jne. nimissä, on merkistöongelmien välttämiseksi varminta käyttää aakkosnumeerisia merkkejä ASCII-taulukon ensimmäisen 128 merkin joukosta (ks. asciitable.com).

2. Sulut ja välilyönnit

• Aloittava lohkosulku { omalla rivillään.

• Lopettava lohkosulku } samassa sarakkeessa aloittavan lohkosulun kanssa.

• Sisennyksessä käytetään 4 välilyöntiä per sisennystaso, ei TAB-merkkiä.

  • Notepad++:ssa näet erikoismerkit näin: View --> Show symbol --> Show all characters.
  • Sisennysasetuksien muuttaminen eri editoreissa: linkki

• Aliohjelmakutsuissa aloittava kaarisulku ( kirjoitetaan kiinni aliohjelman 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)

3. Tyhjät rivit

• Aliohjelmien loppusulun jälkeen kaksi tyhjää riviä.
• Yksi tyhjä rivi kun asiayhteys muuttuu.
• Aliohjelman sisällä tyhjiä rivejä saa olla peräkkäin enintään yksi, ts. turhia tyhjiä rivejä ei saa olla.
• Aliohjelman ensimmäinen ja viimeinen rivi eivät saa olla tyhjiä.

4. Dokumentointi

• Kaikki luokat, aliohjelmat, ja attribuutit tulee dokumentoida käyttämällä XML-muotoisia dokumentaatiokommentteja.
• IDE:n kooditäydennyksen info-ikkunat perustuvat dokumentaatiokommenttien sisältöön

• Lisäksi dokumentaatiokommenttien avulla voidaan tuottaa HTML-sivu automaattisesti.
• 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öä. <-- esimerkki luokan dokumentaatiokommentista
/// </summary>
public class Arvosana
{

  /// <summary>
  /// Opiskelijan nimi
  /// </summary>
  private string opiskelijanNimi = "Antti-Jussi";
    
  // ...
  
  /// <summary>Taulukossa olevien kokonaislukujen keskiarvo <-- esimerkki funktion dokumentaatiokommentista
  /// </summary>
  /// <param name="luvut">Tutkittavien lukujen joukko</param>
  /// <returns>Keskiarvo</returns>
  public static double Keskiarvo(int[] luvut)
  {
    // ...
  } 
}

• Dokumentaatiokommenteissa on mahdollista kirjoittaa myös ComTest-testejä. Näin mielellään myöskin toimitaan kaikissa sellaisissa funktioissa joissa se on kohtuuvaivalla mahdollista.

5. Saantimääreet

Kirjoitetaan näkyville kaikki saantimääreet:

• Yksiluokkaisissa ohjelmissa (tällä kurssilla oletus) attribuuteille asetetaan saantimääreeksi private.
• Metodeille private/protected/public sen mukaan mikä on tarkoituksenmukaista.

5.1 Esimerkki

6. String vai string

Muuttujat esitellään string-sanalla. Kun kutsutaan staattista metodia, niin käytetään String-sanaa.

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

7. Linkkejä

Päälinkit:

• https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/
• https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines

Muita:

• http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf
• http://stackoverflow.com/questions/14967/c-coding-standard-best-practices

8. Nimeämisestä yleisesti

• https://en.wikipedia.org/wiki/Naming_convention_(programming)