FB Informatik Prof. Dr. R.Nitsch. C++ - Dokumentation. Reiner Nitsch r.nitsch@fbi.h-da.de

Transkript

1 C++ - Dokumentation Reiner Nitsch r.nitsch@fbi.h-da.de

2 Software-Dokumentation? Schnelltest: Haben Sie Mut zum Risiko? Um einen knappen Termin zu erreichen, fahren Sie schneller als gewohnt? Nach ein paar Bierchen fahren Sie noch Auto? Gefahren- und Verbotsschilder übersehen Sie gewohnheitsmäßig? Bei Kurzstrecken mit dem Auto legen Sie den Gurt nicht an? Mögen Sie Spiele mit hohen Einsätzen, z.b. Roulette oder Poker? Haben Sie eine Affäre? Falls mehr als 2-mal ja, dann könnte das auch von Ihnen stammen: Software dokumentieren? Keine Zeit! Hauptsache Sie funktioniert. Dabei lieben Sie eine gute Dokumentation aber nur, wenn sie schon fertig geschrieben ist. Leider gilt noch zu oft: Bei Softwareprojekten stirbt die Dokumentation zuerst und die Hoffnung, dass das gut geht, zuletzt C++ Operatoren überladen 2

3 Dokumentation ist wichtig für gute Softwarequalität und Wartbarkeit und muss hoch bewertet und anerkannt werden. muss als Daueraufgabe begriffen werden und darf nicht erst am Ende der Kodierung erfolgen. setzt aber voraus, dass Anforderungen an die Dokumente und die Verantwortlichkeiten klar geregelt sind. Die vollständige Dokumentation zu einem Softwareprodukt besteht aus unterschiedlichen Teilen, die auf verschiedene Zielgruppen ausgerichtet sind (siehe nächste Seite) C++ Operatoren überladen 3

4 Arten der Software-Dokumentation Programmiererdokumentation: Beschreibung des Quellcodes. Methodendokumentation: Allgemeine Beschreibung der Grundlagen, auf denen die Software beruht. (mathematische Algorithmen, technisch-wissenschaftliche oder kaufmännische Verfahren). Installationsdokumentation: beschreibt die Systemvoraussetzungen (Hardware, Software, Betriebssysteme und - Versionen, benötigte Standardbibliotheken und Laufzeitsysteme). Erläuterung der Prozeduren zur Installation, zur Pflege (Updates) und De-Installation. Benutzerdokumentation: Beschreibt die Benutzerschnittstelle für die tatsächlichen Endbenutzer Datendokumentation: detaillierte Beschreibung möglicher Import-/Exportschnittstellen. Testdokumentation Nachweis von Testfällen, mit denen die ordnungsgemäße Funktion jeder Version des Produkts getestet werden können. Entwicklungsdokumentation Nachweis der einzelnen Versionen auf Grund von Veränderungen (z.b. in Pflichtenheften); beteiligte Personen und Organisationseinheiten C++ Operatoren überladen 4

5 Programmiererdokumentation Ansätze moderner Programmiererdokumentation Der Quellcode soll selbsterklärend sein Die Dokumentation soll so weit wie möglich in den Quellcode eingearbeitet sein. Dokumentationswerkzeuge (Javadoc, Doxygen, ) generieren unterstützende Übersichten automatisch aus dem Quellcode und speziell formatierten Kommentaren C++ Operatoren überladen 5

6 Doxygen Tool zur Unterstützung der Programmiererdokumentation Freeware, GNU General Public License. Erzeugt aus speziellen Kommentaren (doc comments) im Quelltext eine übersichtliche Dokumentation in verschiedenen Formaten. Vorteil Die im Quelltext ohnehin erforderliche Beschreibung der Programmstrukturen wird gleichzeitig zum Bestandteil der Dokumentation, Unterstützte Sprachen C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Tcl, Fortran, and D Download der Freeware und des Manuals von der offiziellen Webseite C++ Operatoren überladen 6

7 Doxygen Informationsfluss C++ Operatoren überladen 7

8 Spezielle Kommentarblöcke Ein spezieller Kommentarblock ist ein Kommentar im C++ Stil mit speziellen Markierungen (DocComments) Hinweis: hier wird nur auf Markierungen im Javadoc-Stil eingegangen. Daneben gibt es noch weitere Stile für Kommentarblöcke. DocComments müssen i.d.r. vor der zu dokumentierenden Einheit stehen. Doxygen unterscheidet zwischen Kurzbeschreibungen (einzeilig) und detaillierten Beschreibungen (mehrzeilig) Detaillierte Beschreibung /... text... Die s am Zeilenanfang sind optional: /... text... ist auch möglich. Kurzbeschreibung Beginnt Kommando (DocCommand), endet mit Leerzeile: Brief description. Detailed description starts here. Die speziellen Kommentarblöcke können wahlweise vor der Deklaration (h-datei) oder der Implementierung (cpp-datei) der Programmelemente stehen. Auch ein Aufsplitten ist zulässig. Hinweis: Doxygen kennt noch viele andere DocCommands und Notationen für DocComments C++ Operatoren überladen 8

9 Beispiel: class Demo // Datei: Demo.h (brief) A test class. Note: brief comment blocks are repeated in detail part of documentation! (detail) A more elaborate class description. class Demo { (brief) A private variable. Example for putting documentation (detail) Details for intvar. after members int intvar; float floatvar; /< (detail) Details for floatvar. public: (brief) An enum. Note: brief comment blocks are repeated in detail part of documentation! (detail) More detailed enum description. enum TEnum { TVal1, /< (detail) Enum value TVal1. TVal2, /< (detail) Enum value TVal2. } (brief) Enum pointer. (detail) Details of enumptr. enumptr, C++ Operatoren überladen 9

10 Beispiel: class Demo - Fortsetzung (brief) Enum variable. / (detail) Details of enumvar. enumvar; Example for having separate brief and detailed comments (brief) A constructor. Note: brief comment blocks are repeated in detail part of documentation! (detail) A more elaborate description of the constructor. Demo(); (brief) The destructor. ~Demo(); (brief) Normal Getter function. Note 1: brief comment blocks are repeated in detail part of documentation! Note 2: brief comments may span over more than one Value of (see) setintvar() int getintvar() const; C++ Operatoren überladen 10

11 Beispiel: class Demo - Fortsetzung (brief) Normal setter function. bool setintvar(int val); The detailed comment is placed before the implementation part in file Demo.cpp. }; (brief) A function variable. (detail) Details for function variable int (handler)(int a, int b); C++ Operatoren überladen 11

12 Beispiel: class Demo - Fortsetzung // Datei: Demo.cpp #include "DemoClass.h" Demo::Demo() { } / (detail) A more elaborate description of the destructor. Demo::~Demo() { } / (detail) Value of intvar is only changed if the precondition val (param) New value for true if PRE matches and false if -10 < val < if the precondition matches, intvar has new value val and true will be returned else intvar remains unchanged and false will be (see) getintvar() bool Demo::setPublicVar1(int val) { if( -10<val && val<10 ) { intval=val; return true; } else return false; } C++ Operatoren überladen 12