3.2.2 Quellcode-Dokumentation

Aus SUE

Die Quellcode-Dokumentation wird wie allgemein üblich automatisch aus den Kommentaren im Quellcode generiert. Dies geschieht in der Regel zu jedem Branch / Release.

Nicht nur für die saubere Quellcode-Dokumentation, sondern auch für eine allgemein gute Les- und Wartbarkeit des Codes halten wir uns beim Implementieren an einige Vorgaben. Diese basieren auf dem Original-LSR-CodeStyleGuide.

Formatierungen

Einrückungen werden durch zwei Leerzeichen pro Ebene realisiert.

Nach 80 Zeichen wird eine Code-Zeile umgebrochen, damit sie gut lesbar bleibt.

Design

KlassenNamen, methodenNamen, funktionsNamen, variablen_namen, EINFACHE_KONSTANTEN. Da es sich in Python bei allen Konstrukten schlicht um Objekte handelt, erleichtert diese Namenskonvention ihre Unterscheidung.

Instanz- und Modulvariablen werden initialisiert und auf Standardwerte (z.B. None) gesetzt. Dies geschieht entweder in Klassenkonstruktoren oder soweit oben im Modul wie möglich.

Umfangreiche Module werden in Pakete ausgelagert. Wenn ein Python-Modul (eine .py-Datei) eine große Anzahl von Klassen enthält, wird es in ein Paket umgewandelt (Ordner mit __init__.py und mehreren .py-Modulen).

Sichtbarkeitsregeln. Diese Sichtbarkeitsregeln werden nicht von Python vorgegeben, gelten aber für alle SUE-Entwickler.

Alle Instanzvariablen gelten als protected (nur innerhalb einer Klasse und ihrer Unterklassen verfügbar). Ausnahme: Wenn eine @note im Code die Klasse als struct-like kennzeichnet und auf ihre Attribute direkt zugegriffen werden kann (z.B. AEPor).
Methoden, die mit einem einzelnen Unterstrich beginnen, gelten als protected.
Alle anderen Methoden gelten als public.
Modul-Variablen gelten als private. Die Ausnahme bilden EINFACHE_KONSTANTEN, auf die global, aber nur lesend zugegriffen werden kann.
Wenn auf eine Instanzvariable von außerhalb zugegriffen werden soll, geschieht dies über entsprechende get- und set-Methoden (z.B. getParent, setParent).
Wird der Zugriff auf eine Modulvariable außerhalb des Moduls benötigt, so wird eine entsprechende Top-Level-Funktion definiert.
property(fget, fset) sollte nicht ohne Grund definiert werden, da sie leicht mit einer Instanzvariable verwechselt werden könnte.

Dokumentation

Kommentiert wird gemäß epydoc. Siehe dazu http://epydoc.sourceforge.net/epytext.html und http://epydoc.sourceforge.net/fields.html. Nach dem Generieren der HTML-Dokumente gibt das Log Auskunft über eventuelle Fehler.

Die Felder @todo, @warning, @note und @deprecated werden verwendet, um wichtige Kommentare (auch) für andere Entwickler zu kennzeichnen. Diese Felder werden zusätzlich mit den eigenen Initialen (z.B. @todo: MW: Kommentar) gekennzeichnet.

Schlüsselwortargumente werden, soweit möglich, dokumentiert. Wenn diese Schlüsselwortargumente immer gleich sind, werden das @keyword-Feld verwendet. Dieses funktioniert genau wie @param, verlangt aber nicht, dass der Parameter explizit in den Argumenten der Funktion oder Methoden genannt sein muss.

Anderen Autoren und Mitwirkenden wird durch entsprechende @author-Zeilen im Kopf der Quelltextdatei Anerkennung gezollt.

Fehler, die beim Generieren der Dokumentation angezeigt werden, werden möglichst direkt behoben. Die Dokumentation sollte möglichst valide und up-to-date sein.