Graphics Reference
In-Depth Information
Im Folgenden werden Benennungsmethoden empfohlen.
Kommentare
Softwaredokumentation liegt in zwei Formen vor: extern und intern. Die externe
Dokumentation wie Spezifikationen, Hilfedateien und Entwurfsdokumente wird
außerhalb des Quellcodes verwaltet; auf diese wird hier nicht eingegangen. Die
interne Dokumentation besteht aus Kommentaren, die schon zur Entwurfszeit in
den Quellcode geschrieben werden.
Bei der internen Softwaredokumentation muss sichergestellt werden, dass die
Kommentare parallel zum Quellcode verwaltet und aktualisiert werden. Die ord-
nungsgemäße Kommentierung des Quellcodes ist außerordentlich wertvoll für
die Softwarewartung.
-
Kommentieren Sie alles, was nicht sofort aus dem Code ersichtlich ist.
-
Halten Sie beim Ändern von Code die entsprechenden Kommentare auf dem
aktuellen Stand.
-
Erstellen Sie Kommentare in einheitlichem Format und mit einheitlicher In-
terpunktion und Struktur.
-
Schreiben Sie Kommentare in Form von vollständigen Sätzen. Kommentare
sollen den Code erläutern und nicht seine Verständlichkeit erschweren.
-
Umgeben Sie einen Blockkommentar nicht mit einem typografischen Rah-
men. Dieser mag attraktiv aussehen, erschwert jedoch die Verwaltung.
-
Erstellen Sie Kommentare während des Codierens, da Sie später keine Zeit
dafür haben. Außerdem werden Sie bei einer erneuten Überprüfung des Co-
des (möglicherweise ihres eigenen) feststellen, dass der zum Zeitpunkt der
Erstellung leicht verständliche Code sechs Wochen später Rätsel aufgibt.
-
Erklären Sie in standardisierten Kommentaren den Zweck, die Voraussetzun-
gen, die Einschränkungen sowie die Leistungsfähigkeit gleich am Anfang
einer Routine.
-
Kommentieren Sie Code, der aus Schleifen und logischen Verzweigungen be-
steht. Dies sind Schlüsselbereiche, in denen Leser des Quellcodes unterstützt
werden müssen.
-
Fügen Sie keine langatmigen Kommentare am Ende einer Codezeile hinzu;
sie verschlechtern die Lesbarkeit des Codes. Kommentare am Ende von Zei-
len eignen sich nur für Anmerkungen zu Variablen-Deklarationen. Richten
Sie in diesem Fall alle Zeilenendkommentare an einem gemeinsamen Tab-
stop aus.
-
Vermeiden Sie überflüssige Kommentare, z. B. eine ganze Zeile mit Stern-
chen. Trennen Sie stattdessen Kommentare und Code durch Leerraum.
-
Entfernen Sie vor der Weitergabe alle temporären oder überzähligen Kom-
mentare aus der Entwicklungsphase, um Verwirrung bei der zukünftigen Ver-
waltung zu vermeiden.
