Kommentierung & Dokumentation SE Programmierstil, Wind Markus, 2002. Überblick/Kommentierung Kommentierung Self-documenting code Arten von Kommentaren

Kommentierung & Dokumentation

SE Programmierstil, Wind Markus, 2002.

Überblick/Kommentierung

Kommentierung

Self-documenting code

Arten von Kommentaren

Wie wird kommentiert ?

Konsistenz und Automatisierung



Überblick/Dokumentation

Dokumentation

interne/externe Dokumentation

Probleme von Dokumentationen

Funktionen einer Dokumentation

Entwicklungsprinzipien

Layout von Dokumentationen



Self-documenting code/Beispiel

for(i=1;i<=Num;i++){

MeetsCriteria[i]=true;

for(i=2;i<=Num/2;i++){

j=i+i;

while(j<=Num){

MeetsCriteria[j]=false;

j=j+i;

}}

for(i=1;i<=Num;i++){

if(MeetsCriteria[i])

System.out.println(i);

for(primeCand=1;primeCand<=Num;primeCand++)

IsPrime[primeCand]=true;

for(factor=2;factor<=Num/2;factor++){

factNumber=factor+factor;

while(factNumber<=Num){

IsPrime[factNumber]=false;

factNumber=factNumber+factor;

}

}

for(primeCand=1;primeCand<=Num;primeCand++)

if(IsPrime[primeCand]

System.out.println(primeCand);



Self-documenting code (1)

Funktionen: beschreibender Name eine klar definierte Aufgabe verständliches Interface

Datenorganisation: Zusätzliche Variablen wenn nötig ADT mit minimaler Komplexität und Schnittstelle




Variablen- und Konstanten: beschreibende Namen Verwendung nur für beschriebenen Zweck Konstanten mit beschreibendem Namen Bezeichnung unterscheidet zwischen Typen

Layout: Layout entspricht dem logischen Aufbau




Kontrollstruktur: Kapselung von zusammengehörenden Anweisungen Normalablauf folgt dem „if-Zweig“ minimale Komplexität der Kontrollstrukturen minimale Verschachtelung keine komplexen booleschen Konstrukte



Arten von Kommentaren (1)

erklärende Kommentare: komplizierte, trickreiche und sensible Stellen ist der Code zu kompliziert ?

markierende Kommentare: verbleiben nicht im Code vom Compiler erkannt/nicht erkannt



Arten von Kommentaren (2)

inhaltliche Kommentare: was tut ein Abschnitt im Code ?

zusammenfassende Kommentare: kompakte Prosabeschreibung



effizientes Kommentieren

keine optisch aufwendigen Kommentare schwer wartbar hoher Zeitaufwand

keine komplizierte Sprache fehlendes Codeverständnis ? schwer nachvollziehbar

Die folgende Folie zeigt Beispiele für ineffizienteKommentare:



effizientes Kommentieren/Beispiel

/*******************************************

* Mein wunderschön eingerahmter Kommentar *

*******************************************/

// mein ineffizient unterstrichener Kommentar

// +--------------------------------------------------+

// score............aktueller Punktestand

// topScore......höchster erzielter Punktestand



Wie wird kommentiert ? / Allgemein (1)

keine Wiederholung des Codes

was passiert, nicht wie passiert es

vor dem zu kommentierenden Codeteil

vernünftige Anzahl an Kommentaren




„überraschende“ Effekte werden dokumentiert Links- oder Rechtsshift Multiplikation oder Division

keine Abkürzungen in Kommentaren

Bugs und undokumentierte Features werden dokumentiert

nahe beim betroffenen Code




Verletzungen im Programmierstil dokumentieren „break“ zum Beenden von Schleifen beim Compilerbau

schlechten Code neu schreiben anstatt kommentieren

Kommentare konsistent halten



Wie wird kommentiert ? / Einzelzeilen

Gründe für kommentierte Einzelzeilen: komplexe Anweisung Fehlervermerk/Entwicklungsnotizen

gute Eignung für Deklarationen

Kennzeichnung von Blockbeginn und -ende



Wie wird kommentiert ? / Blöcke

Keine Einzelzeilenkommentare zur Blockbeschreibung Schwere Zuordenbarkeit



Wie wird kommentiert ? / Funktionen

allgemeine Beschreibung der Funktion Was tut die Funktion ? Einschränkungen I/O-Spezifikation globale Effekte

Komplexe Beschreibung nicht für jede Funktion strCopy() nach obiger Definition überkommentiert



Wie wird kommentiert ? / Deklarationen

Einheiten werden kommentiert

Bereiche werden kommentiert

codierte Bedeutungen werden kommentiert Static final int NEW=1, MODIFY=2,...



Wie wird kommentiert ? / Klassen

gilt auch für Programme, Module, etc.

von einem „Top-View“ aus kommentieren Aufgabe Inhalt Nicht zu detailliert

Kontaktinformationen



Konsistenz und Automatisierung

Schwer konsistent haltbare Informationen werden, wenn möglich, nicht kommentiert exportierte Funktionen Entwicklungsverlauf Abhängigkeiten ...

Automatisierungswerkzeuge



interne/externe Dokumentation

interne Dokumentation bleibt in der Firma / im Entwicklungsteam

externe Dokumentation für den Anwender / Endkunden bestimmt



Probleme von Dokumentationen

Fachsprache schwer verständlich, lesbar

Konsistenz nicht aktuell, unvollständig, widersprüchlich

Gestaltung Layout, fehlendes Stichwortverzeichnis, etc.



Funktionen einer Dokumentation (1)

Anleitungsfunktion

Produktpräsentation/Entscheidungsgrundlage

Bedienungsanleitung

Wartung und Weiterentwicklung der Software

Kontroll- und Nachweisfunktion

interne und externe Prüfung

Kontrolle des Entwicklungsfortschritts



Funktionen einer Dokumentation (2)

Kommunikationsfunktion Basis für Entwickler, Auftraggeber/Auftragnehmer gesteigerte Wiederverwendbarkeit gesteigerte Vergleichbarkeit



Entwicklungsprinzipien (1)

entwicklungsbegleitende Dokumentation

Benutzerorientierung

Kommentierung

Dokumentationswerkzeuge Zeitersparnis, Effizienz



Entwicklungsprinzipien (2)

grafische Darstellung Skizzen, Tabellen, etc. im Allgemeinen ER-Diagramme, UML, etc. im Entwicklungsbereich

ansprechende Gestaltung Layout Index, Inhaltsverzeichnis, Querverweise Zusammenfassungen und Beispiele



Layout von Dokumentationen (1)

Gestaltungsmöglichkeiten sinnvoll nutzen

Einsatz von Tabellen: effiziente Datenpräsentation Einheiten, Ausrichtung, Linien, etc.

Informationen über verwendete Daten

Konsistenz sicherstellen



Layout von Dokumentationen (2)

logische Gliederung

Vernünftige Dimensionierung von grafischen Elementen Skizzen, Bilder, Diagramme, etc.

Konsistente Verwendung der Layoutmöglichkeiten Schriftgröße für Kapitelüberschriften

Documents

Kommentierung & Dokumentation SE Programmierstil, Wind Markus, 2002. Überblick/Kommentierung Kommentierung Self-documenting code Arten von Kommentaren