Coding Conventions

Aus Das Sopra Wiki



Mit Coding Conventions sind ein mehr oder weniger fester Satz von Regeln gemeint, an die sich alle an einem Projekt teilnehmenden Programmierer halten sollten um den Quellcode leichter les- und wartbar zu machen. Hierbei werden zum Beispiel Namenskonventionen und ihre Schreibweise ausgemacht. Aber auch auf die Einrückungstiefe des Quellcodes, das Benutzen von Leerzeichen oder Tabstopps sowie andere Richtlinien bei der Codeerstellung kann hier eingegangen werden.


Naming & Style Conventions

In diesem Abschnitt wird beschrieben nach welchen Regeln Klassen, Typen, Variabeln usw. benannt werden müssen.

Naming Conventions

Typen, Klassen, Methoden & Konstanten

Für die Bennenung von Type, Klassen, Methoden und Konstanten benutzen wird die Namenkonventionen aus Pascal. Diese sehen vor, dass die Anfangsbuchstaben groß geschrieben werden und der Rest klein.

Dies gilt auch für zusammengesetzte Namen wie z.B."DefaultSize". 

public class SomeClass 
{ 
   const int DefaultSize = 100; 
   public void SomeMethod() 
   { 
     // do something
   } 
}


Lokale Variablen & Methoden Parameter

Bei Variabel wird die Namenkonventionen verwendet die in Camel üblich ist. Diese unterscheiden sich geringfügig von den Konvention aus Pascal.

Der einzige unterschied ist, dass der Name am Anfang klein geschrieben wird. 

void MyMethod(int someNumber) 
{ 
   int number; 
}


Interfaces

Bei Interfaces wird dem Klassen- und Dateinamen ein "I" vorangestellt. 

interface INewInterface 
{ 
   // 
}


Private Klassenvariablen

Einer Private Klassenvariablen wird ein "_" vorangestellt, die Variable wird dann nach den Camel-Case Konventionen benannt. 

public class SomeClass3 
{ 
   private int _number; 
}


Exceptions

Bei Benutzerdefinierten Exceptions Klassen wird dem Namen der Klasse das Wort "Exception" angehängt. 

public class FooException : Exception
{ 
  //
}


Naming Style

Enum
Properties

Regeln für das Sinnvolle benennen von Properties:

  • Verwende Substantive oder Sätze bestehend aus Substantive.
  • Verwende Pascal Namingconventions.
public class Test
{
    //...
    public string TestCase
    {
        get;
        set;
    }
}
Methoden

Regeln für das Sinnvolle benennen von Methoden:

  • Benutze Paare bestehend aus einem Verb und dem Objektname z.B. ShowDialog().
  • Methoden die einen Wert zurückgeben, sollte eine Beschreibung des Wertes im Namen haben z.B. GetObjectState().


Variabeln

Regeln für das Sinnvolle benennen von Variablen:

  • Verwende anschauliche Namen
    • Verwende keine Buchstaben als Variablennamen wie z.B. i oder t. Benutze stattdessen index oder temp. (Ausnahme sind die Zählvariablen in For - Schleifen)
    • Verwende keine Hungarian Notation
    • Verwende keine Abkürzungen z.B. num statt number.
Generische Typen

Verwende bei generischen Typen den Buchstaben T für einzelne Parameter. 

public class List<T> 
{ 
  // 
}

Sollte der generische Typ mehrere Parameter haben, wird dem T ein anschaulicher Namen in der Pascal Naming Convention angehängt. 

//Correct: 
public class LinkedList<TKey,TValue> 
{ 
  // 
} 
//Avoid: 
public class LinkedList<K,V> 
{ 
  // 
}

White Space & Wrapping Lines

Beschreibt Regeln für Abstände und Zeilenumbrüche.

White Space

Blank Lines

Zeileabstände sind wichtig, um die Lesbarkeit des geschrieben Codes zu erhöhen.

Aus diesem Grund sollte eine Zeile Abstand nach folgendem Code kommen:

  • Properties
  • Zwischen Klassen und Interfaces
  • Methoden
  • Lokalen Variabeln in Methoden
  • Logischen Abschnitten in Methoden
    • z.B. zwischen unterschiedlichen Berechnungen.
    • z.B. Abschnitt A erzeugt einen String und Abschnitt B arbeitet mit diesem weiter.
  • Logischen Abschnitten innerhalb einer Klasse bzw. eines Sourcefiles
    • z.B. zwischen Privat und Public Methoden
    • z.B. zwischen #region MyName Statements


Inline Spaces

Ein Leerzeichen sollte immer nach Kommas oder Semikolons kommen, vorausgesetzt die Zeile ist nach dem Semikolon nicht zu Ende. 

//Correct: 
foo(expr1, expr2);

int number = 5 + 5;

//Avoid: 
foo(expr1,expr2);

int number=5+5;
Table like formatting

Ordne eine Codeblock tabellenartig an 

string test = "TestString";
int number = 15 + 5;
number++;

Wrapping Lines

Sollte ein Statement zu lang für eine Zeile sein, dann benutze die folgenden Regeln um diese auf mehrere Zeilen aufzuteilen:

  • Mache einen Zeilenumbruch nach:
    • einem Komma
    • einem Operator
    • nach abgeschlossenen Klammern, d.h. geklammert Ausdrücke nicht über mehrere Zeile aufbrechen


Versuch Ausdrücken wie z.B. Methoden Parameter untereinaner Anzuorden: 

//Correct: 
foo(expr1, expr2, expr3, expr4,
    expr5);

//Avoid: 
foo(expr1, expr2, expr3, expr4
, expr5);

Das gleiche gilt auch für arithmetisch Ausdrücke: 

//Correct: 
var test = 4 * 4 / (3 - 2 + 1) +
           8 * 1;

//Avoid (Bad Style): 
var test = 4 * 4 / (3 - 2 + 
           1) + 8 * 1;

Kommentare

Dieser Abschnitt beschäftigt sich mit dem sinnvollen Kommentieren innerhalb des Source Codes. Kommentare sind ein wichtiger Bestandteil bei entwicklen von Projekten, sie diennen einmal zum Verständnis des Source Codes und zu anderen können sie eine Art Dokumentation sein.


Single Line Comments

Diese Kommentare, die nur eine Zeile lang sind, werden mit // begonnen. Desweiteren werden Single Line Comments verwendet, um Code auszukommentieren, hierfür gibt in den unterschiedlichen Entwicklungsumgebungen bereits eine Tastenkombination. (Visual Studio: Strg+E,C) 

//Do something 

//foo("expr1","expr2","expr3",expr4,
//    "expr5");

Block Comments

Kommentare die über mehrere Zeile stehen zwischen /* Your Comment */ stehen. Diese sollte nur verwendet werden, um Code innerhalb eine Funktion oder eine Properties zu kommentieren. Für Beschreibung von gesamten Methoden, Properties oder Klassen sollte die Documentation Comments verwendet werden. 

/* I'am 
* a 
* comment
*/


Documentation Comments

Dieser XML ähnliche Kommentartype wird so Dokumentieren von Methoden, Properties und Klassen verwendet. Bei Visual Studio ist es ohne weiteres möglich diese Kommentare als XML Datei zu exportieren und als Schnitstellenbschreibung (API) oder sogar als vollständige Dokumentation auszubereiten. 


/// <summary>
/// Baut einen String aus Vorname und Nachname
/// </summary>
/// <param name="name">Name</param>
/// <param name="vorname">Vorname</param>
/// <returns>String mit vollständigen Namen</returns>
public string CreateNameString(string name, string vorname)
{
  String sname = String.Format("{0}, {1}", name, vorname);
  return sname;
}

Coding Style

Deklaration

In diesem Abschnitt wird gezeigt wie Variablen, Deklariert und Intializiert werden.

Anzahl von Deklaration
  • Es wird im Empfohlen pro Zeile nur ein Variable zu deklarieren und diese zu kommentiere
int level; // indentation level
int size; // size of table
  • Keine unterschiedlichen Variablen Typen in einer Zeile
//Correct: 
string testString; 
int number;

//Avoid: 
string testString; int number;
  • Verwende eindeutige Namen zur Benennung von Variablen
int a, b; //What is 'a'? What does 'b' stand for?
Initialisierung
  • Intialisiere Variablen bei ihrer Deklaration.
string testString = "Hello I'm a Test String";
int number = obj.Length;
  • Bei Dialogen und Objekten die nach ihrer Verwendung nicht mehr benötigt werden, verwende das using Statement.
using (OpenFileDialog openFileDialog = new OpenFileDialog()) {
...
}


Deklaration von Klassen und Interfaces
  • Kein Leerzeichen zwischen Methodennamen und dem "(".
  • { kommen immer in eine neue Zeile nach ein Deklaration
  • Das gleiche wie bei "{" gilt auch für die "}".
Class MySample : MyClass, IMyInterface
{
	int myInt;
	public MySample(int myInt)
	{
	  this.myInt = myInt ;
	}

	void Inc()
	{
	  ++myInt;
	}

	void EmptyMethod()
	{
	}
}
Abgerufen von „https://sopranium.de/index.php?title=Coding_Conventions&oldid=3647“