Coding Conventions: Unterschied zwischen den Versionen

Aus Das Sopra Wiki
← Zum vorherigen Versionsunterschied
VisuellWikitext
Hofmann (Diskussion | Beiträge)
sopra
83 Bearbeitungen
Langenfeld (Diskussion | Beiträge)
Bürokraten, sopra, sopra17, sopra18, sopradozenten, soprapre17, Administratoren
1.252 Bearbeitungen
K Änderungen von Dietsch (Diskussion) wurden auf die letzte Version von Greitschus zurückgesetzt
Markierung: Zurücksetzung
 
(22 dazwischenliegende Versionen von 4 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Stub}}
{{Stub}}


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


Die Coding Conventions, die Sie im SoPra verwenden, werden durch das Visual Studio Plugin Resharper (im [[Downloads|Downloadbereich]] herunterladbar) durchgesetzt. Jeder Teilnehmer des Softwarepraktikums hat sich an diese Coding Conventions zu halten. Die Coding Conventions für ReSharper sind in der Datei [[Datei:UserSettings.zip]] enthalten. Eine Installationsanleitung für die benutzerspezifischen Einstellungen befindet sich [[Downloads#ReSharper|hier]]. Es ist wichtig, dass Ihr Programm keine Warnungen und Fehlermeldungen von ReSharper enthält (vgl. [[Anforderungen#Technische Anforderungen|Technische Anfoderungen]]).


=== Naming & Style Conventions ===
Die genauen Einzelheiten der Coding Conventions finden Sie bitte selbst heraus. Hier soll nur eine kurze Liste der wichtigsten Dinge benannt werden:
In diesem Abschnitt wird beschrieben nach welchen Regeln Klassen, Typen, Variabeln usw.
benannt werden müssen.


==== Naming Conventions ====
== Namenskonventionen ==


===== Typen, Klassen, Methoden & Konstanten =====
Die folgenden Namenskonventionen sind einzuhalten:


Für die Bennenung von [[Datentyp|Type]], [[Klasse|Klassen]], [[Methode|Methoden]] und Konstanten
* [[Datentyp|Typen]] und [[Namensraum|Namespaces]]: <tt>UpperCamelCase</tt>
benutzen wird die Namenkonventionen aus Pascal. Diese sehen vor, dass die Anfangsbuchstaben groß geschrieben werden und der Rest klein.
* [[Interface]]s: <tt>IUpperCamelCase</tt>
* [[Generic|Typ Parameter]]: <tt>TUpperCamelCase</tt>
* [[Methode]]n, [[Property|Properties]] und Events: <tt>UpperCamelCase</tt>
* Lokale [[Variable]]n: <tt>lowerCamelCase</tt>
* Lokale [[Variable#Konstanten|Konstanten]]: <tt>lowerCamelCase</tt>
* [[Methode#Parameter|Parameter]]: <tt>lowerCamelCase</tt>
* [[Klasse|Felder]] (nicht private): <tt>mUpperCamelCase</tt>
* Instanzvariablen (private): <tt>mUpperCamelCase</tt>
* Statische Felder (nicht private): <tt>sUpperCamelCase</tt>
* Konstante Felder (nicht private): <tt>UpperCamelCase</tt>
* Konstante Felder (private): <tt>UpperCamelCase</tt>
* Statische [[Modifizierer|Readonly]] Felder (nicht private): <tt>sUpperCamelCase</tt>
* Statische Readonly Felder (private): <tt>sUpperCamelCase</tt>
* [[Enum]] Member: <tt>UpperCamelCase</tt>
* Alles andere: <tt>UpperCamelCase</tt>


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


* Geschweifte Klammern stehen immer alleine in einer Zeile (einzige Ausnahme sind einzeilige [[Property|Properties]]). Beispiel:
<source lang="csharp">
<source lang="csharp">
public class SomeClass
class Class1
{  
{
   const int DefaultSize = 100;  
   private int mVariable;
  public void SomeMethod()
  {
    // do something
  }
}
</source>


  // Braces in methods
  int Main()
  {
      int a = 3;
      if (a < 3)
      {
        return 1;
      }
      else
      {
        return 0;
      } 
  }


===== Lokale Variablen & Methoden Parameter =====
  // Single-line Property
 
  public int Variable
Bei Variabel wird die Namenkonventionen verwendet die in Camel üblich ist. Diese unterscheiden sich geringfügig von den Konvention aus Pascal.
  {
 
      get { return mVariable; }
Der einzige unterschied ist, dass der Name am Anfang klein geschrieben wird.
      set { mVariable = value; }
 
   }
<source lang="csharp">
void MyMethod(int someNumber)
{
   int number;
}
}
</source>
</source>


 
* Runde Klammern (zum Beispiel bei der Verwendung von Parametern) haben keine Leerzeichen nach dem Öffnen der Klammer:
===== Interfaces =====
 
Bei Interfaces wird dem Klassen- und Dateinamen ein "I" vorangestellt.
 
<source lang="csharp">
interface INewInterface
{
  //
}
</source> [[Kategorie:Code-Beispiele]]
 
 
===== Private  Klassenvariablen =====
 
Einer Private Klassenvariablen wird ein "_" vorangestellt, die Variable wird dann nach den Camel-Case Konventionen benannt.
 
<source lang="csharp">
<source lang="csharp">
public class SomeClass3
void Method(string s)
{
  private int _number;
}
</source> [[Kategorie:Code-Beispiele]]
 
 
===== Exceptions =====
 
Bei Benutzerdefinierten Exceptions Klassen wird dem Namen der Klasse das Wort "Exception" angehängt.
 
<source lang="csharp">
public class FooException : Exception
{
  //
}
</source>
 
 
==== Naming Style ====
 
===== Enum =====
 
 
===== Properties =====
 
Regeln für das Sinnvolle benennen von Properties:
*Verwende Substantive oder Sätze bestehend aus Substantive.
*Verwende Pascal Namingconventions.
 
<source lang="csharp">
public class Test
{
{
    //...
    public string TestCase
    {
        get;
        set;
    }
}
}
</source> [[Kategorie:Code-Beispiele]]
===== 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''' [http://de.wikipedia.org/wiki/Ungarische_Notation Hungarian Notation]
**Verwende '''keine''' Abkürzungen z.B. num statt number.
===== Generische Typen =====
Verwende bei generischen Typen den Buchstaben T für einzelne Parameter.
<source lang="csharp">
public class List<T>
{
  //
}
</source>
</source>


Sollte der generische Typ mehrere Parameter haben, wird dem T ein anschaulicher Namen in der Pascal Naming Convention angehängt.
== Sprache im Code ==
 
<source lang="csharp">
//Correct:
public class LinkedList<TKey,TValue>
{
  //
}
//Avoid:
public class LinkedList<K,V>
{
  //
}
 
</source> [[Kategorie:Code-Beispiele]]
 
=== 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.
 
<source lang="csharp">
//Correct:
foo(expr1, expr2);
 
int number = 5 + 5;
 
//Avoid:
foo(expr1,expr2);
 
int number=5+5;
</source> [[Kategorie:Code-Beispiele]]
 
===== Table like formatting =====
 
Ordne eine Codeblock tabellenartig an
 
<source lang="csharp">
//Correct:
foo(expr1, expr2);
 
 
//Avoid:
foo(expr1,expr2);
</source> [[Kategorie:Code-Beispiele]]
 
==== 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:
 
<source lang="csharp">
//Correct:
foo(expr1, expr2, expr3, expr4,
    expr5);
 
//Avoid:
foo(expr1, expr2, expr3, expr4
, expr5);
</source>
 
Das gleiche gilt auch für arithmetisch  Ausdrücke:
 
<source lang="csharp">
//Correct:
var test = 4 * 4 / (3 - 2 + 1) +
          8 * 1;
 
//Avoid (Bad Style):
var test = 4 * 4 / (3 - 2 +
          1) + 8 * 1;
</source>
 
=== 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 wird // verwendet um Code auszukommentieren, hierfür gibt in den unterschiedlichen Entwicklungsumgebungen bereits eine Tastenkombination. (Visual Studio: Strg+E,C) 
 
<source lang="csharp">
//Do something
 
//foo("expr1","expr2","expr3",expr4,
//    "expr5");
</source> [[Kategorie:Code-Beispiele]]
 
==== 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.
 
<source lang="csharp">
/* I'am
* a
* comment
*/
</source> [[Kategorie:Code-Beispiele]]
 
==== 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.
 
 
<source lang="csharp">
/// <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;
}
</source> [[Kategorie:Code-Beispiele]]
 
=== Coding Style ===
 
==== Deklaration ====


Die vornehmliche Sprache für alles, was mit dem Quelltext zu tun hat, ist Englisch. Das bedeutet, dass alle Variablen-, Methoden- und Klassenvariablen englisch benannt werden, um die Verständlichkeit des Codes zu erhöhen. Auch für Kommentare wird Englisch empfohlen, ist hier jedoch nicht ganz so wichtig.


[[Kategorie:Begriffe]]
[[Kategorie:Begriffe]]
[[Kategorie:Entwurf]]
[[Kategorie:MS01]] [[Kategorie:Code-Beispiele]]

Aktuelle Version vom 5. August 2021, 12:09 Uhr



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.

Die Coding Conventions, die Sie im SoPra verwenden, werden durch das Visual Studio Plugin Resharper (im Downloadbereich herunterladbar) durchgesetzt. Jeder Teilnehmer des Softwarepraktikums hat sich an diese Coding Conventions zu halten. Die Coding Conventions für ReSharper sind in der Datei Datei:UserSettings.zip enthalten. Eine Installationsanleitung für die benutzerspezifischen Einstellungen befindet sich hier. Es ist wichtig, dass Ihr Programm keine Warnungen und Fehlermeldungen von ReSharper enthält (vgl. Technische Anfoderungen).

Die genauen Einzelheiten der Coding Conventions finden Sie bitte selbst heraus. Hier soll nur eine kurze Liste der wichtigsten Dinge benannt werden:

Namenskonventionen

Die folgenden Namenskonventionen sind einzuhalten:

  • Typen und Namespaces: UpperCamelCase
  • Interfaces: IUpperCamelCase
  • Typ Parameter: TUpperCamelCase
  • Methoden, Properties und Events: UpperCamelCase
  • Lokale Variablen: lowerCamelCase
  • Lokale Konstanten: lowerCamelCase
  • Parameter: lowerCamelCase
  • Felder (nicht private): mUpperCamelCase
  • Instanzvariablen (private): mUpperCamelCase
  • Statische Felder (nicht private): sUpperCamelCase
  • Konstante Felder (nicht private): UpperCamelCase
  • Konstante Felder (private): UpperCamelCase
  • Statische Readonly Felder (nicht private): sUpperCamelCase
  • Statische Readonly Felder (private): sUpperCamelCase
  • Enum Member: UpperCamelCase
  • Alles andere: UpperCamelCase

Klammerung

  • Geschweifte Klammern stehen immer alleine in einer Zeile (einzige Ausnahme sind einzeilige Properties). Beispiel:
class Class1
{
   private int mVariable;

   // Braces in methods
   int Main()
   {
      int a = 3;
      if (a < 3)
      {
         return 1;
      }
      else
      {
         return 0;
      }  
   }

   // Single-line Property
   public int Variable
   {
      get { return mVariable; }
      set { mVariable = value; }
   }
}
  • Runde Klammern (zum Beispiel bei der Verwendung von Parametern) haben keine Leerzeichen nach dem Öffnen der Klammer:
void Method(string s)
{
}

Sprache im Code

Die vornehmliche Sprache für alles, was mit dem Quelltext zu tun hat, ist Englisch. Das bedeutet, dass alle Variablen-, Methoden- und Klassenvariablen englisch benannt werden, um die Verständlichkeit des Codes zu erhöhen. Auch für Kommentare wird Englisch empfohlen, ist hier jedoch nicht ganz so wichtig.

Abgerufen von „https://sopranium.de/index.php?title=Coding_Conventions&oldid=10117“