Kommentierung Dokumentation berblickKommentierung Selfdocumenting code Arten von Kommentaren

Kommentierung & Dokumentation Überblick/Kommentierung Self-documenting code Arten von Kommentaren Wie wird kommentiert ? Konsistenz und Automatisierung SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Überblick/Dokumentation interne/externe Dokumentation Probleme von Dokumentationen Funktionen einer Dokumentation Entwicklungsprinzipien Layout von Dokumentationen SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Self-documenting code/Beispiel for(i=1; i<=Num; i++){ Meets. Criteria[i]=true; for(i=2; i<=Num/2; i++){ j=i+i; while(j<=Num){ Meets. Criteria[j]=false; j=j+i; }} for(i=1; i<=Num; i++){ if(Meets. Criteria[i]) System. out. println(i); for(prime. Cand=1; prime. Cand<=Num; prime. Cand++) Is. Prime[prime. Cand]=true; for(factor=2; factor<=Num/2; factor++){ fact. Number=factor+factor; while(fact. Number<=Num){ Is. Prime[fact. Number]=false; fact. Number=fact. Number+factor; } } for(prime. Cand=1; prime. Cand<=Num; prime. Cand++) if(Is. Prime[prime. Cand] System. out. println(prime. Cand); SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation 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 SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Self-documenting code (2) § 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 SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Self-documenting code (3) § Kontrollstruktur: § § § Kapselung von zusammengehörenden Anweisungen Normalablauf folgt dem „if-Zweig“ minimale Komplexität der Kontrollstrukturen minimale Verschachtelung keine komplexen booleschen Konstrukte SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation 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 SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Arten von Kommentaren (2) § inhaltliche Kommentare: § was tut ein Abschnitt im Code ? § zusammenfassende Kommentare: § kompakte Prosabeschreibung SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation 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 ineffiziente Kommentare: SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation effizientes Kommentieren/Beispiel /********************** * Mein wunderschön eingerahmter Kommentar * **********************/ // mein ineffizient unterstrichener Kommentar // +-------------------------+ // score. . . aktueller Punktestand // top. Score. . . höchster erzielter Punktestand SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation 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 SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Wie wird kommentiert ? / Allgemein (2) § „überraschende“ Effekte werden dokumentiert § Links- oder Rechtsshift Multiplikation oder Division § keine Abkürzungen in Kommentaren § Bugs undokumentierte Features werden dokumentiert § nahe beim betroffenen Code SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Wie wird kommentiert ? / Allgemein (3) § Verletzungen im Programmierstil dokumentieren § „break“ zum Beenden von Schleifen beim Compilerbau § schlechten Code neu schreiben anstatt kommentieren § Kommentare konsistent halten SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Wie wird kommentiert ? / Einzelzeilen § Gründe für kommentierte Einzelzeilen: § komplexe Anweisung § Fehlervermerk/Entwicklungsnotizen § gute Eignung für Deklarationen § Kennzeichnung von Blockbeginn und -ende SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Wie wird kommentiert ? / Blöcke § Keine Einzelzeilenkommentare zur Blockbeschreibung § Schwere Zuordenbarkeit SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation 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 § str. Copy() nach obiger Definition überkommentiert SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Wie wird kommentiert ? / Deklarationen § Einheiten werden kommentiert § Bereiche werden kommentiert § codierte Bedeutungen werden kommentiert § Static final int NEW=1, MODIFY=2, . . . SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Wie wird kommentiert ? / Klassen § gilt auch für Programme, Module, etc. § von einem „Top-View“ aus kommentieren § Aufgabe § Inhalt § Nicht zu detailliert § Kontaktinformationen SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Konsistenz und Automatisierung § Schwer konsistent haltbare Informationen werden, § § § wenn möglich, nicht kommentiert exportierte Funktionen Entwicklungsverlauf Abhängigkeiten. . . § Automatisierungswerkzeuge SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation interne/externe Dokumentation § interne Dokumentation § bleibt in der Firma / im Entwicklungsteam § externe Dokumentation § für den Anwender / Endkunden bestimmt SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Probleme von Dokumentationen § Fachsprache § schwer verständlich, lesbar § Konsistenz § nicht aktuell, unvollständig, widersprüchlich § Gestaltung § Layout, fehlendes Stichwortverzeichnis, etc. SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation 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 SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Funktionen einer Dokumentation (2) § Kommunikationsfunktion § Basis für Entwickler, Auftraggeber/Auftragnehmer § gesteigerte Wiederverwendbarkeit § gesteigerte Vergleichbarkeit SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Entwicklungsprinzipien (1) § entwicklungsbegleitende Dokumentation § Benutzerorientierung § Kommentierung § Dokumentationswerkzeuge § Zeitersparnis, Effizienz SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Entwicklungsprinzipien (2) § grafische Darstellung § Skizzen, Tabellen, etc. im Allgemeinen § ER-Diagramme, UML, etc. im Entwicklungsbereich § ansprechende Gestaltung § Layout § Index, Inhaltsverzeichnis, Querverweise § Zusammenfassungen und Beispiele SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation Layout von Dokumentationen (1) § Gestaltungsmöglichkeiten sinnvoll nutzen § Einsatz von Tabellen: § effiziente Datenpräsentation § Einheiten, Ausrichtung, Linien, etc. § Informationen über verwendete Daten § Konsistenz sicherstellen SE Programmierstil, Wind Markus, 2002.

Kommentierung & Dokumentation 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 SE Programmierstil, Wind Markus, 2002.