1
Überblick/Kommentierung

• Kommentierung
• Self-documenting code
• Arten von Kommentaren
• Wie wird kommentiert ?
• Konsistenz und Automatisierung

2
Überblick/Dokumentation

• Dokumentation
• interne/externe Dokumentation
• Probleme von Dokumentationen
• Funktionen einer Dokumentation
• Entwicklungsprinzipien
• Layout von Dokumentationen

3
Self-documenting code/Beispiel

• for(i1iltNumi)
• MeetsCriteriaitrue
• for(i2iltNum/2i)
• jii
• while(jltNum)
• MeetsCriteriajfalse
• jji
• for(i1iltNumi)
• if(MeetsCriteriai)
• System.out.println(i)

• for(primeCand1primeCandltNumprimeCand)
• IsPrimeprimeCandtrue
• for(factor2factorltNum/2factor)
• factNumberfactorfactor
• while(factNumberltNum)
• IsPrimefactNumberfalse
• factNumberfactNumberfactor
• for(primeCand1primeCandltNumprimeCand)
• if(IsPrimeprimeCand
• System.out.println(primeCand)

4
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
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
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
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
Arten von Kommentaren (2)

• inhaltliche Kommentare
• was tut ein Abschnitt im Code ?
• zusammenfassende Kommentare
• kompakte Prosabeschreibung

9
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
effizientes Kommentieren/Beispiel

• /
• Mein wunderschön eingerahmter Kommentar
  
• /
• // mein ineffizient unterstrichener Kommentar
• // ----------------------------------------------
  ----
• // score............aktueller Punktestand
• // topScore......höchster erzielter Punktestand

11
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
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
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
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
Wie wird kommentiert ? / Blöcke

• Keine Einzelzeilenkommentare zur
  Blockbeschreibung
• Schwere Zuordenbarkeit

16
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
Wie wird kommentiert ? / Deklarationen

• Einheiten werden kommentiert
• Bereiche werden kommentiert
• codierte Bedeutungen werden kommentiert
• Static final int NEW1, MODIFY2,...

18
Wie wird kommentiert ? / Klassen

• gilt auch für Programme, Module, etc.
• von einem Top-View aus kommentieren
• Aufgabe
• Inhalt
• Nicht zu detailliert
• Kontaktinformationen

19
Konsistenz und Automatisierung

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

20
interne/externe Dokumentation

• interne Dokumentation
• bleibt in der Firma / im Entwicklungsteam
• externe Dokumentation
• für den Anwender / Endkunden bestimmt

21
Probleme von Dokumentationen

• Fachsprache
• schwer verständlich, lesbar
• Konsistenz
• nicht aktuell, unvollständig, widersprüchlich
• Gestaltung
• Layout, fehlendes Stichwortverzeichnis, etc.

22
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
Funktionen einer Dokumentation (2)

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

24
Entwicklungsprinzipien (1)

• entwicklungsbegleitende Dokumentation
• Benutzerorientierung
• Kommentierung
• Dokumentationswerkzeuge
• Zeitersparnis, Effizienz

25
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
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
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