Programmieren mit Harald R. Haberstroh

Diese Programmierrichtlinien sind für den Programmierunterricht an der HTL Wiener Neustadt, Abteilung Informatik gedacht, sind aber auch für andere ganz praktisch (nach diversen Anpassungen).

Sammlung von Programmierrichtlinen, die für alle Programmiersprachen gelten.

- Verwenden Sie sprechende Namen (für Funktionen, Variable, Methoden usw.)
- Jede Variablendeklaration muss in einer eigenen Zeile stehen.
- Keine Umlaute in Namen (auch wenn sei von der Programmiersprache erlaubt werden).
- Keine Tabulatoren verwenden. Der Editor (vim, eclipse usw.) muss so eingestellt werden, sodass nur Leerzeichen eingefügt werden.
- Einrückungen dürfen nur mit Leerzeichen erfolgen. Eine Ebene muss mindestens zwei Leerzeichen eingerückt werden. Mehr als vier Leerzeichen sind nicht sinnvoll.
- Die Länge von Zeilen soll nicht größer als 79 Zeichen sein. Zeilen, die deshalb umgebrochen werden müssen, sind nach dem Zeilenumruch (eventuell mit Zeilenfortsetzungszeichen zu markieren) zusätzlich einzurücken.
- Dateinamen, Verzeichnisnamen dürfen keine Umlaute, Sonderzeichen und Leerzeichen enthalten.
- Jede Programmdatei muss einen Kommentarkopf mit folgenden Inhalten haben:

Ihrem Namen
Ihrer Klasse
Ihrer Katalognummer
Ihrer Evidenznummer (und/oder E-Mail-Adresse)
dem Dateinamen
Kurzbeschreibung des Programms oder der Klasse (Zweck)

- Funktionen, Subroutinen, Methoden müssen mindestens durch eine Leerzeile getrennt werden.
- Klassennamen müssen mit einem Großbuchstaben beginnen. Klassennamen sind normalerweise Substantive in der Einzahl.
- Methodennamen müssen mit einem Kleinbuchstaben beginnen. Methoden beschreiben eine Tätigkeit!
- Konstante definieren. Es dürfen keine Zahlen unmotiviert im Code verwendet werden.
- Links und rechts je binären Operator genau ein Leerzeichen.
- Nach einem unären Operator kein Leerzeichen, jedoch davor schon.
- Keine Leerzeichen unmittelbar innerhalb von runden, eckigen oder geschweiften Klammern.
- Keine Leerzeichen vor runder Klammer von Funktionen.
- Keine Leerzeichen vor Komma, Strichpunkt, Punkt oder Doppelpunkt. Ein Leerzeichen nach Komma, Strichpunkt und Doppelpunkt, aber kein Leerzeichen nach einem Punkt.
- Fixe Dateipfade müssen als Konstante definiert werden. Noch besser wäre die Verwendung von Konfigurationsdateien.
- Bei Vergleichen sollte die Konstante immer links stehen, damit nicht versehentlich eine Zuweisung entsteht.
- Globale Variable sollten vermieden werden.
- Alle Methoden (Funktionen), die nur lokal in einer Klasse oder einem Modul verwendet werden, müssen privat sein (je nach Programmiersprache z.B. private oder static).
- Der Zweck von Parametern/Variablen/Methoden muss durch den Namen erkennbar sein. Alternativ kann auch (zusätzlicher) Kommentar verwendet werden.
- Sichern Sie den Code mit assertions (Zusicherungen assert()) ab.
- Verwenden Sie englische Kommentare und Bezeichner (wenn möglich, die folgenden Beispiele wurden noch ohne diese Regel verfasst).

Python

Grundsätzlich gelten obige Richtlinien. Es folgt ein Beispielprogrammkopf zur Demonstration:

#!/usr/bin/python
# -"- coding: UTF8 -*-
# hauf.py
# Worthäufigkeiten ermitteln, indem ein Dictionary mit Worten erzeugt wird.
# Danach wird das Dictionary in eine Liste umgewandelt (mit Elementen der
# Art [häufigkeit,wort]), um ein Sortieren nach Häufigkeit zu ermöglichen.
# Eingelesen wird alles und mittels Regulärem Ausdruck in eine Wortliste
# zerlegt.
#
# 2006-10-12, Maier Lukas, 2BD, 20, d09999

Der Header enthält den Dateinamen hauf.py, den Namen Maier Lukas, die Klasse 2BD, die Katalognummer 20 und die Evidenznummer d09999. Darüberhinaus wird der Zweck des Programms kurz umrissen.
Jede Methode bzw. Funktion soll einen DocString enthalten (zwischen "), in dem der Zweck der Methode und die Parameter beschrieben werden:

def einlesen(fp):
   """
   Einlesen der Wörter aus der Datei fp, liefert eine Liste von Worten
   """
   text = fp.read()                 # lies alles ein
   # ... Rest fehlt

Siehe auch PEP 8 -- Style Guide for Python Code oder PEP 8 - Übersetzung

Java

- Paketnamen sind klein zu schreiben
- Klassennamen beginnen mit einem Großbuchstaben und werden in KamelSchreibWeise geschrieben
- Methoden beginnen mit einem Kleinbuchstaben und werden in kamelSchreibweise geschrieben
- Verwenden Sie Javadoc-Strings in Ihren Komentaren.
- Jede Datei Soll wieder einen Header haben, z.B.:

/**
 * automat: bo.Tabelle.java Automaten zeichnen.
 *
 * @author Maier Lukas, 2BD, 20, d09999
 */
package bo;
//...

Hier ist zusätzlich der Paketname im Kommentar angegeben (bo).
- Jede Klasse muss ebenfalls einen Header haben, der den Zweck beschreibt, z.B.:

/**
 * Übergangstabelle eines Automaten. Zeilen sind Knoten (Zustände), Spalten sind
 * Mengen von Eingabesymbolen.
 *
 * @author Maier Lukas, 2BD, 20, d09999
 */
public class Tabelle {
    private HashMap<string> knoten = new HashMap<string>();
  //...

- Ist nur eine Klasse in einer Datei, so können die beiden Header zusammengefasst werden.
- Methoden sollten mindestens @param und @return Docstrings enthalten:

/**
 * Leerstring.
 *
 * @param anz
 *          Anzahl Blanks
 * @return String mit anz Leerzeichen
 */
private String leer(int anz) {
  String ret = "";
  //...

Am besten machen Sie sich schon passende Vorlagen in eclipse (Menü Window->Preferences):

Siehe auch Code Conventions for the Java Programming Language

C#

Hier gilt im Wesentlichen das selbe wie für Java, nur dass die Docstrings ein anderes Format haben (XML), ein Beispiel:

/// <summary>
///  Diese Funktion gibt den größeren Betrag zurück
/// </summary>
/// <param name="a">Der erste Übergabeparameter
/// <param name="b">Der zweite Übergabeparameter
/// <returns>Die Zahl mit dem größeren Betrag  </returns>
/// <remarks>Diese Funktion gibt den größeren Betrag der beiden Übergegeben
/// <see cref="Int32"/>  zurück.
/// Sind die Beträge gleich groß ist dies ein Fehler</remarks>
/// <exception cref="ArgumentException">Der Betrag der beiden Zahlen ist gleich
/// groß</exception>
public int GetGreaterAbs(int a, int b)
{
   return Math.Max(Math.Abs(a), Math.Abs(b));
}

Siehe auch C# Coding Conventions (C# Programming Guide)

C, C++

Beide Sprachen sind wie Java zu dokumentieren. Hier gibt es externe Programme zur Auswertung der DocStrings.

andere Sprachen

Die Regeln müssen entsprechend adaptiert werden. Etliche Sprachen haben ein ähnliches Format für DocStrings wie Java. Bitte verwenden Sie diese Tags.

Labels: allgemeines, coding conventions, programmierrichtlinien