Allgemeine Regeln

1. Klassenbezeichner fangen mit einem Großbuchstaben an. Sie sind i.a. ein Substantiv im Singular. GUI-Klassen erhalten den Anhang GUI (EingabefensterGUI). Man kann Klassen auch durch ein vorangestelltes "T" oder "K" kennzeichnen.
2. Objektbezeichner fangen mit einem kleinen Buchstaben an und enden in der Regel mit einem Klassenbezeichner. Man kann Objekte auch durch ein vorangestelltes "o" kennzeichnen.
3. Attributbezeichner fangen im Deutschen in der Regel ebenfalls mit einem Großbuchstaben an, sie sind von Klassen leicht durch das vorangestellte "self." zu unterscheiden.
4. Methodenaufrufe werden kleingeschrieben und enden mit einer Klammer, die ggf. leer ist. Zumeist beinhalten Methodenaufrufe ein Verb. Verfasser, die den imperativen Sprachen verhaftet sind, verwenden in der Literatur in der Regel die Befehlsform, andere Autoren benutzen die Verben u.a. in der Grundform. Bezeichner von Standardmethoden heißen z.B.: getAttributname(), setAttributname(), isAttributname()
5. Als Bezeichner werden problemnahe Bezeichner verwendet. Nichtöffentliche Bezeichner fangen mit zwei Unterstreichungszeichen an.
6. In der Regel werden deutsche Bezeichner verwendet, im programmiersprachlichen Kontext dürfen auch englische Fachbezeichner verwendet werden (push, get)

Jede (öffentliche) Klasse und jede Methode ist unmittelbar hinter der entsprechenden Deklarationszeile mit Hilfe eines Python-Doc-Strings zu erläutern. Wir verabreden, dabei mehrzeilige Doc-Strings mit folgendem Format zu verwenden:

Beispiel:

   def plus(self):
         """
         /*  Die Methode plus (ohne Parameter)
         /*  inkrementiert das Attribut Zählerstand.
         /* Bereichsüberschreitungen werden NICHT abgefragt!
         """
         QUELLTEXT ....

Wendet man das weiter unten angegebene Script (pmdoc = python mini doc) auf den Quelltext solcher Pythonprogramme an, so erhält man beispielsweise folgende Ausgabe:

PYTHON-MINI-DOC                         Kokavecz 2000
-----------------------------------------------------
Datum:         21.02.2000 (Monday)
Uhrzeit:       23:27:14
Bearbeiter:    Bernd Kokavecz
Projekt: 
Verzeichnis:   /usr2/home/l/koka/Aprogramme/DIVERSE_PROJEKTE/python/html/python-m-doc
Datei:         zaehler0.py
-----------------------------------------------------

class Zaehler:                              
    /* Klasse Zaehler
    /* stellt einen einfachen Zähler dar. 
--
  def __init__(self):                       
    /* Bei der Instanziierung wird das Attribut
    /* zaehlvar=0  gesetzt.
--
  def loeschen(self):                           
    /* Methode loeschen
    /* setzt das Attribut zaehlvar=0
--
  def hochzaehlen(self):                        
    /* Methode hochzählen
    /* inkrementiert das Attribut zaehlvar.
--
  def hat_Zaehlerstand(self):                   
    /* Methode  hat_Zaehlerstand
    /* liefert den Zählerstand zurück.

Auf Wunsch erlaubt das Script sofort das Verschicken der Dokumentation an den Lehrer! Fehlen irgendwelche Kommentare, so fehlen auch die Zeilen, in denen die Klassen und Methoden deklariert werden. Fehlende Kommentare fallen also sofort auf.

class Zaehler:                              
    """
    /* Klasse Zaehler
    /* stellt einen einfachen Zähler dar. 
    """
  def __init__(self):                       
    """
    /* Bei der Instanziierung wird das Attribut
    /* zaehlvar=0  gesetzt.
    """
    self.zaehlvar=0 

  def loeschen(self):                           
    """
    /* Methode loeschen
    /* setzt das Attribut zaehlvar=0
    """
    self.zaehlvar=0
    self.zaehlvar=0

  def hochzaehlen(self):                        
    """
    /* Methode hochzählen
    /* inkrementiert das Attribut zaehlvar.
    """
    self.zaehlvar=self.zaehlvar+1

  def hat_Zaehlerstand(self):                   
    """
    /* Methode  hat_Zaehlerstand
    /* liefert den Zählerstand zurück.
    """
    return self.zaehlvar

pmdoc sollte immer in dem Verzeichnis angewendet werden, in dem auch die Quelltexte liegen. In diesem Verzeichnis benötigt man Schreibrechte. Das Script selber ist vom Systemverwalter irgendwo abzulegen und sollte sich über die Umgebungsvariable PATH erreichen lassen, damit der Aufruf einfach wird (pmdoc).

Hier der Quelltext des entsprechenden Unix-Scripts (pmdoc), mit dem die Kommentare gefiltert und um bestimmte Angaben ergänzt werden: (quick and dirty, but beautiful)

echo
if ! test -f $1; then
   echo "FEHLER! Python-Datei nicht gefunden"!
else
   echo > $1.doc
   echo "PYTHON-MINI-DOC                         Kokavecz 2000" >> $1.doc
   echo "-----------------------------------------------------" >> $1.doc
   date '+Datum:         %d.%m.%Y (%A)' >> $1.doc
   date '+Uhrzeit:       %T' >> $1.doc
   echo -n "Bearbeiter:    " >> $1.doc
   # folgende umstaendliche Programmierung ist ab Suse 6.4 erforderlich (Macke bei logname?)
   logname > .$1.x
   cat /etc/passwd | grep "^`cat .$1.x`:"| cut -d: -f5 >> $1.doc
   echo "Projekt: " >> $1.doc
   echo -n "Verzeichnis:   " >> $1.doc
   pwd >> $1.doc
   echo -n "Datei:         " >> $1.doc
   echo $1 >> $1.doc
   echo "-----------------------------------------------------" >> $1.doc
   echo >> $1.doc
   cat $1 | grep "\/\*" -B2 | grep -v \"\"\" >> $1.doc
   echo >> $1.doc
   cat $1 | grep -v \"\"\" |  grep -v "\/\*" > $1.ohne_doc
   echo -n "$1.doc erzeugt! Per e-mail an Lehrer schicken? (j/n) "
   read antwort
   if test $antwort = 'j'; then
      if ! test -f $HOME/.lehrer ; then
          echo -n "e-mail-Adresse des Lehrers: "
          read lehrer
          echo $lehrer > $HOME/.lehrer
          echo "Habe e-mail-Adresse unter $HOME/.lehrer gepeichert!"
      fi
      cat $1.doc | mail `cat $HOME/.lehrer`
   fi
fi
echo

Mit dem Script pmdh, das Sie beim Download dieser Dokumentation im Verzeichnis pyhon-m-doc finden, erhalten Sie wie bei javadoc sogar eine Dokumentation im HTML-Format.