Kommentierung & Dokumentation SE Programmierstil, Wind Markus, 2002. Überblick/Kommentierung...
-
Upload
mariele-ederer -
Category
Documents
-
view
111 -
download
2
Transcript of Kommentierung & Dokumentation SE Programmierstil, Wind Markus, 2002. Überblick/Kommentierung...
Kommentierung & Dokumentation
SE Programmierstil, Wind Markus, 2002.
Überblick/Kommentierung
Kommentierung
Self-documenting code
Arten von Kommentaren
Wie wird kommentiert ?
Konsistenz und Automatisierung
Kommentierung & Dokumentation
SE Programmierstil, Wind Markus, 2002.
Überblick/Dokumentation
Dokumentation
interne/externe Dokumentation
Probleme von Dokumentationen
Funktionen einer Dokumentation
Entwicklungsprinzipien
Layout von Dokumentationen
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);
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
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
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
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
Kommentierung & Dokumentation
SE Programmierstil, Wind Markus, 2002.
Arten von Kommentaren (2)
inhaltliche Kommentare: was tut ein Abschnitt im Code ?
zusammenfassende Kommentare: kompakte Prosabeschreibung
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 ineffizienteKommentare:
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
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
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
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
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
Kommentierung & Dokumentation
SE Programmierstil, Wind Markus, 2002.
Wie wird kommentiert ? / Blöcke
Keine Einzelzeilenkommentare zur Blockbeschreibung Schwere Zuordenbarkeit
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
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,...
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
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
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
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.
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
Kommentierung & Dokumentation
SE Programmierstil, Wind Markus, 2002.
Funktionen einer Dokumentation (2)
Kommunikationsfunktion Basis für Entwickler, Auftraggeber/Auftragnehmer gesteigerte Wiederverwendbarkeit gesteigerte Vergleichbarkeit
Kommentierung & Dokumentation
SE Programmierstil, Wind Markus, 2002.
Entwicklungsprinzipien (1)
entwicklungsbegleitende Dokumentation
Benutzerorientierung
Kommentierung
Dokumentationswerkzeuge Zeitersparnis, Effizienz
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
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
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