Initial Commit

OU3/CODING_STYLE.md

@@ -0,0 +1,98 @@
+# Kodkonvention
+
+I detta dokument beskrivs den kodkonvention som har följts/ska följas
+för kod som läggs till kodbasen. Konventionen är till stor del baserad
+på kodkonventionen som följs i Linux-kärnan. Därför kommer läsaren
+hänvisas till dokumentet med den officiella kernelkonventionen.
+
+
+# Linuxkärnans kodkonvention
+
+Se [Linux kernel coding style](https://www.kernel.org/doc/html/v4.10/process/coding-style.html).
+Nedan följer en uppräkning av vilka punkter vi ska följa, samt
+eventuella avvikelser från dessa. Om en punkt från dokumentet ovan ej
+nämns nedan så gäller punkten ej.
+
+## 1. Indentation
+
+Indenteringskonventionen ska följas helt och hållet. Det är möjligt att
+konfigurera utvecklingsmiljön (e.g. Codelite) att automatiskt indentera
+korrekt.
+
+## 2. Breaking long lines and strings
+
+Denna punkt är också mycket viktig, samt något din utvecklingsmiljö kan 
+hantera eller varna för.
+
+## 3. Placing Braces and Spaces
+
+Här ska alla punkter följas (även de under 3.1), med ett undantag:
+Ensamma satser i t.ex. if-satser *ska* ha måsvingar.
+
+## 4. Naming
+
+När det kommer till namngivning är det viktigt att ha i åtanke att koden
+tillsammans med kommentarerna ska tydligt förklara syftet med koden. Därför är
+det viktigt att konventionen som beskrivs under `4. Naming` tolkas med detta i
+hänsyn. Det innebär till exempel att om koden blir enklare att läsa med
+variabelnamnet `counter` istället för `c` eller `tmp`, bör `counter` användas
+istället.
+
+## 5. Typedefs
+
+Här avviker kursen från Linuxkärnans kodkonvention. För att främja
+datatypernas gränsytor och göra dem så lik de teoretiska gränsytorna
+som möjligt så används `typedefs` för t.ex. `struct list_pos`. I
+Linuxkärnan hade motsvarande implementation krävt att det skrevs
+`struct list_pos pos` överallt, medan datatyperna givna på kursen
+förenklar detta till `list_pos pos`. Det viktiga här är att lära sig
+gränsytorna.
+
+## 6. Functions
+
+Denna konvention ska följas så som den presenteras. Långa funktioner kommer
+under denna kurs alltid vara onödigt, dela upp i mindre funktioner! Det ökar
+läsbarheten, förenklar debugging, samt gör det enklare att diskutera koden.
+
+## 7. Centralized exiting of functions
+
+Det finns anledningar till att `goto` används i Linuxkärnan (e.g.
+bakåtkompabilitet), men under denna kurs ska ni ej använda detta.
+
+## 8. Commenting
+
+Följ det första exemplet för kommentarer. Det finns exempel i de givna
+datatyperna på hur funktioner kan dokumenteras.
+
+## 14. Allocating memory
+
+I Linuxkärnan finns inte `malloc` och `calloc`, motsvarande funktioner heter
+`kmalloc` samt `kcalloc`. Vi kommer under denna kurs att översätta Linuxkärnans
+konvention till följande:
+
+```c
+p = malloc(sizeof(*p));
+```
+
+samt 
+
+```c
+p = calloc(n, sizeof(*p));
+```
+
+Det är fullt möjligt att i det senare fallet vända på parametrarna (i.e.
+`calloc(sizeof(*p), n)`) då storleken på minnet som allokeras beräknas som
+första argumentet gånger det andra argumentet (i.e., 
+`n*sizeof(*p) == sizeof(*p)*n`).
+
+## 16. Function return values and names
+
+Här är det första och sista stycket vad som är viktigt att följa. Om en funktion
+returnerar huruvida funktionen lyckades eller ej så signifierar `0` ett lyckat
+anrop, och negativa värden signifierar fel (e.g. `-1` om en fil inte finns, `-2`
+om filen inte gick att läsa). Om en funktion returnerar en pekare `p`, så 
+indikerar `p == NULL` att funktionen inte lyckades.
+
+# Avslutning
+
+Det finns visst rum för tolkning under några av dessa punkter.