Eine all zu oft vernachlässigte Möglichkeit beim Programmieren ist die Beschreibung von Programmcode in der Quelldatei selbst. Die Shell kennt zur Beschreibung im Programmcode nur ein Symbol, welches in Scripten allerdings noch eine weitere Bedeutung hat.

Kommentare dienen im wesentlichen der Übersicht des Programmcodes und der kurzen Erläuterung über die wesentliche Aufgabe oder Funktion der jeweiligen Programmsektionen. Die Shell kennt zur Kennzeichnung eines Kommentars lediglich ein Symbol. Das Nummernzeichen ( # ).

Oft wird noch ein einleitender Kommentarblock erstellt, der Angaben über den Programmierer, die Programmversion und wichtige Merkmale des Programmcodes selbst enthält. Vergleichbare einleitende und abschließende Tags wie bei anderen Programmiersprachen, bietet die Shell nicht. Daher muss ein auch Kommentarblock in jeder Zeile mit einem einleitenden Nummernzeichen beginnen.

Im weiteren Verlauf werden dann Programmsektionen und ihre Arbeitsweise mit mit kurzen (möglichst Einzeiler) aber aussagekräftigen Beschreibungen versehen. Bei umfangreicheren Scripten kann man mittels des Kommentarzeichens Programmabschnitte aufteilen.

Allgemein sollte mit Kommentaren auch deshalb sparsam umgegangen werden, da jedes weitere Zeichen im Programmcode die Größe beeinflusst. Bei umfangreicheren Scripten allerdings fallen die zusätzlichen Zeichen für Kommentare weniger ins Gewicht und der Vorteil der Lesbarkeit überwiegt den Nachteil des zusätzlich erforderlichen Speicherplatzes.

Anmerkung: Für eine umfangreiche und genaue Erläuterung sollte eine separate Textdatei beigefügt werden. Dort können dann alle Informationen (Versionshistory, genaue Arbeitsweise, bekannte Probleme, etc.) nach belieben dokumentiert werden.

Ein gutes positives Beispiel soll im Folgenden genauer betrachtet werden:

#!/bin/bash

# Program: Unit Converter
# Version: 0.9b
# Author:  Max Musterman
# Commercial use? -> mail[at]maxmusterman[dot]com
# Problems? -> visit board.maxmusterman.com

convert_units ()
{
  cf=$(units "$1" "$2" | sed --silent -e '1p' | awk '{print $2}')
  # Strip off everything except the actual conversion factor.
  echo "$cf"
}  

Unit1=miles
Unit2=meters
cfactor=`convert_units $Unit1 $Unit2` 
quantity=3.73

result=$(echo $quantity*$cfactor | bc)

echo "There are $result $Unit2 in $quantity $Unit1."

exit 0

Das Script beginnt mit der Zeichenfolge #!/bin/bash. Damit wird die Shell-Variante angegeben, in der das Script ausgeführt werden soll. Dies ist nicht zwingend erforderlich, da man ein Script auch manuell einer Shell zuweisen kann. Allerdings unterscheidet sich der Funktionsumfang der Shell-Varianten in manchen Punkten und die korrekte Ausführung ist möglicherweise nicht bei allen Shell-Varianten gegeben.

Folgt also in der ersten Zeile auf das Nummernzeichen ein Ausrufungszeichen ( #! ), dann interpretiert die Shell dies nicht als Kommentar, sondern erwartet daraufhin die Angabe der zu verwendenden Shell-Variante. Dies ist der einzige Fall wo das Nummernzeichen innerhalb eines Scripts nicht der Kommentierung dient.

Daraufhin folgt ein kleiner Kommentarblock, wo Programmversion, Autor, eine E-Mail Adresse und ein Hilfeforum vermerkt sind. Hier wird nochmal deutlich, dass ein Kommentarblock in jeder Zeile mit dem Nummernzeichen eingeleitet werden muss.

Im Programm selbst findet man nur einen Kommentar, der nach der Auffassung des Programmierers an dieser Stelle hilfreich sein könnte. Die Eingabemanipulation innerhalb der Funktion convert_units ().

Aus diesem Beispiel lassen sich einige Regeln für die Anwendung von Kommentaren ableiten:

• Die Zeichenfolge Nummernzeichen Ausrufungszeichen ( #! ) in der ersten Zeile eines Scripts dient nicht der Kommentierung, sondern leitet die zu verwendende Shell-Variante ein.
• Kommentare werden mit dem Nummernzeichen ( # ) eingeleitet.
• Kommentare können an jedem beliebigen Platz im Programmcode platziert werden.
• Kommentarblöcke müssen in jeder Zeile mit dem Nummernzeichen ( # ) eingeleitet werden.
• Kommentare so kurz wie möglich halten.
• Kommentare nur dort anwenden, wo sie sinnvoll sind.
  

Gerade die letzte Regel bereitet die größten Schwierigkeiten. Denn das genaue Maß für die Anwendung von Kommentaren zu finden ist nicht zuletzt vom Kenntnisstand des Programmierers abhängig. Während man anfangs noch dazu neigen würde jeden Arbeitsschritt kommentieren zu müssen, schwindet dieses Verlangen mit zunehmendem Kenntnisstand über die Programmiersprache.

Daher sollen abschließend noch zwei Leitsätze zum Einsatz von Kommentaren mit auf den Weg gegeben werden:

• Keine Kommentierung von Programmcode, dessen Arbeitsweise sich selbst erklärt, bzw. sich mit Unterstützung der Hilfedateien schnell selbst ermitteln lässt.
• Kommentierung nur bei komplexen Kommandos.

Anmerkung: Mir sei veziehen, dass ich diese Regeln auf dieser Website oft breche, was aber lediglich dem Grund tribut zollt, dass beta06.de einen Lernauftrag erfüllen soll.