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

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

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

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

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

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

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

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

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

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

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

Kommentierung & Dokumentation SE Programmierstil, Wind Markus, Wie wird kommentiert ? / Allgemein (2) ü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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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