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

Präsentation zum Thema: "Kommentierung & Dokumentation SE Programmierstil, Wind Markus, 2002. Überblick/Kommentierung Kommentierung Self-documenting code Arten von Kommentaren."—  Präsentation transkript:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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