FH Wedel Logo


Dokumentationsrichtlinien
Archiv
Stand: Juli 1994

Inhaltsverzeichnis


Einleitung

Die Erstellung einer Dokumentation zu einem für das Programmierpraktikum entwickelten Programm dient der praktischen Anwendung der Techniken aus den Vorlesungen zur Softwareentwicklung. Die Qualität der Dokumentation beeinflusst wesentlich die Entscheidung, ob ein Programm testiert wird oder nicht, bzw. in der Fachrichtung IA die Note für das Programm. Die grundlegenden Elemente, die eine Dokumentation in der Regel beinhalten muss, werden in diesen Dokumentationsrichtlinien beschrieben. Je nach Problemstellung, Programmumfang oder Programmaufgabe können sich zusätzliche Elemente ergeben, die zu einer Dokumentation gehören, z.B. Beschreibung zusätzlicher Hardware, oder aber einige Elemente entfallen, z.B. Dateibeschreibungen. Diese Dokumentationsrichtlinien treten am 01. Juli 1994 in Kraft und sind für alle Schüler/-innen und Studenten/-innen verbindlich. Änderungen und/oder Ergänzungen zu dieser Version werden durch Aushang im Schaukasten zwischen den Rechenzentren 2 und 3 bekanntgegeben.


Formale Anforderungen

Die Dokumentation ist in einem sauberen DIN A4 Schnellhefter abzugeben. Dabei ist auf ausreichende Heft- und Korrekturränder zu achten. Programmlistings müssen lesbar abgelegt sein, also ebenfalls mit Heftrand, nicht über die Perforation gedruckt und nicht als Endloslisting. Handschriftliche Dokumentationen sind zu vermeiden. Falls sich Handskizzen nicht vermeiden lassen, können sie eingefügt werden, der allgemeine Fließtext sollte jedoch in gedruckter Form vorliegen. Die einzelnen Seiten dürfen nicht in Klarsichthüllen verpackt sein. Der Quellcode, das ausführbare Programm bzw. das Lademodul und benötigte Datendateien sind auf Datenträgern abzugegeben (3,5"). Diese sind so zu verpacken, daß sie einfach herausgenommen werden können. Hierfür bietet sich eine DIN A4 Klarsichthülle an, die einmal gefaltet und vor das Deckblatt geheftet wird. Bei Programmen, die auf Mehrplatzsystemen erstellt wurden, sind die BenutzerID und alle erforderlichen Kennworte anzugeben. Die Abgabe von Disketten entfällt hierbei.


Aufbau der Dokumentation

Deckblatt

Das Deckblatt soll alle Daten enthalten, die zur Klassifizierung von Programm und Ersteller/in notwendig sind. Dieses sind im einzelnen:
  • Name, Matrikelnummer, Fachbereich, Fachsemester
  • Programmiersprache
  • Programmname, Thema
Bei DOS-Programmen ist zusätzlich anzugeben, mit welchem Programm (in welcher Version) eine Virenüberprüfung durchgeführt wurde.

Inhaltsverzeichnis

Es ist ein vollständiges, gegliedertes Inhaltsverzeichnis mit Seitenzahlen anzulegen.

Allgemeine Problemstellung

In diesem Teil der Dokumentation soll die Problematik, die der Programmentwicklung zugrunde liegt, dargestellt werden, und zwar unabhängig von der programmtechnischen Realisierung. Auch soll aufgeführt werden, welche Teile des Problems durch das Programm abgedeckt werden. Bei Seminaraufgaben ist dieser Teil durch die Aufgabenstellung vorgegeben.

Benutzerhandbuch

Mit dem Benutzerhandbuch wird der unerfahrene Benutzer in die Lage versetzt, das Programm zu installieren bzw. zu starten und ordnungsgemäß zu bedienen. Dazu gehören die Dokumentationspunkte:

Ablaufbedingungen

Dieser Abschnitt enthält Informationen darüber, welche Voraussetzungen für den Programmstart erforderlich sind, welche Hardware (z.B. Grafikkarte, Monitor) und Software (in welcher Version) erforderlich ist, welche Dateien in welchen Verzeichnissen vorhanden oder z.B. sortiert sein müssen. Es ist zu bedenken, daß die Ablaufbedingungen normalerweise von der Entwicklungskonfiguration abweichen.

Programminstallation und Programmstart

Welche Kommandos sind erforderlich, um das Programm zu installieren und zu starten? Welche Fehler können dabei auftreten, und wie werden diese behoben? Sollte eine umfangreiche Installation erforderlich sein, so ist ein Installationsbatch mitzuliefern.

Bedienungsanleitung

An diese Stelle gehört eine Beschreibung der angebotenen Funktionen und wie sie aktiviert werden, also wie der Benutzer vorgehen muß, um seine Probleme zu lösen bzw. mit dem Programm zu arbeiten. Zur Verdeutlichung und Orientierung ist es auch sinnvoll, an dieser Stelle Hardcopies der Benutzeroberfläche einzufügen. Die Ein- und Ausgabedaten (Inhalte und Formate) sind zu beschreiben.

Fehlermeldungen

Welche Fehlermeldungen gibt es? Wie ist darauf zu reagieren? Eine Aufbereitung dieser Informationen in Form einer Tabelle ist am kompaktesten (Meldung / Bedeutung / Maßnahme).

Wiederanlaufbedingungen

Was passiert beim Programmabbruch (z.B. durch Systemfehler oder Stromausfall)? Welche Maßnahmen sind ggf. erforderlich, um einen ordnungsgemäßen Wiederanlauf zu ermöglichen?

Programmiererhandbuch

Es gilt der Grundsatz der Transparenz: Ein Programm muß von einem sachverständigen Dritten in "angemessener Zeit" überblickt und geprüft werden können. Dieser Teil der Dokumentation soll also einem Programmierer einen übersichtlichen Einblick in das Programm geben und somit die Wartung ermöglichen. Dazu gehören folgende Dokumentationspunkte:

Entwicklungskonfiguration

  • Betriebssystem, Compiler, Tools (jeweils Name und Version)
  • Hardware

Problemanalyse und Realisation

Es soll dargestellt werden, mit welcher Konzeption bzw. nach welchem Algorithmus das Programm umgesetzt worden ist. Es ist zu erklären, warum etwas so und nicht anders gelöst wurde. Dieser Abschnitt ist völlig unabhängig von der verwendeten Programmiersprache zu halten.

Beschreibung grundlegender Datenstrukturen

Hier werden die Datenorganisation und die Datenstrukturen zur Problemlösung beschrieben. Dazu zählt der Aufbau, die Größe der einzelnen Komponenten und speziell bei dynamischen Strukturen die Verzeigerung untereinander. In diesem Zusammenhang ist auch der Aufbau der vom Programm benutzten Datendateien zu beschreiben (vgl. Dateibeschreibungstabelle).

Programmorganisation

Ein Programmorganisationsplan (POP) gibt die Aufrufhierarchie aller Unterprogramme eines Programms wieder. Noch besser als ein einfacher POP ist eine Darstellung in Form von Structure-Charts.

EVA-Diagramme

Für Datenbankprogramme und Programme anderer Programmiersprachen, die mehrere Dateien bearbeiten und/oder Listenausgaben unterstützen, ist ein EVA-Diagramm anzulegen. EVA-Diagramme für Programme, die Bildschirm, Tastatur und maximal eine Datei verwenden, sind nicht erforderlich.

Beschreibung der Module

Die folgenden Beschreibungen sollten Inline erfolgen. Besteht eine Unterteilung in INTERFACE- und IMPLEMENTATION-Teil, so erfolgt die Schnittstellenbeschreibung im Interface, während die Beschreibung der Funktion des Moduls in die Implementation gehört.

Beschreibung der Schnittstellen

Hier ist eine Beschreibung des Moduls als BLACK BOX gefordert. Dies kann am besten in Form einer Tabelle erfolgen (vgl. Modulschnittstellentabelle). Folgende Angaben sollten vorhanden sein:
  • Modulname
  • Kurzbeschreibung in wenigen aussagefähigen Sätzen
  • Parameter
  • Globale Zugriffe, falls sie nicht zu vermeiden sind
  • Voraussetzungen für den Aufruf:
    z.B. Wertebereiche von Parametern, geöffnete Dateien o.ä.
  • Eigenschaften der Resultate:
    z.B. Funktionsergebnis genügt einer mathematischen Formel.
  • Fehlerfälle / Fehleraktionen:
    z.B. Fehlerhafte Parameter werden neu eingelesen.

Beschreibung der Funktion der Module

Auch diese Beschreibung gehört bei Hochsprachen in den Modulkopf. Sie sollte inhaltlich zwischen der Kurzbeschreibung und der Inline-Dokumentation liegen und der Konvention "So grob wie m”glich, so fein wie n”tig!" folgen. Als Darstellungstechnik kommt Pseudocode zur Anwendung. Alternativ können auch Struktogramme gezeichnet und der schriftlichen Dokumentation beigefügt werden. Flußdiagramme sollten vermieden werden, da sich sonst Abläufe ergeben können, die der strukturierten Programmierung nicht genügen. Speziell Assembler sollte möglichst im Pseudocode, in Ausnahmefällen als PASCAL-Äquivalent, dokumentiert werden. In Hochsprachen sollte auch dieser Punkt inline behandelt werden, es brauchen allerdings nur die wichtigsten Abläufe beschrieben werden. Bei maschinennahen Sprachen ist diese Ausführung für jedes Modul in der schriftlichen Dokumentation beizufügen.

Hinweise zur Kommentierung

Die Kommentare sollen dem inhaltlichen Verständnis der Programmlogik dienen. Sie sollen nicht Grundlagen der Programmiersprache beschreiben! Beispiel:

Gut: index:=index+1; {Fachindex auf nächsten Satz}
Schlecht: index:=index+1; {Variable index um eins erhöhen}

Es soll also der Hintergrund der Anweisung, nicht die Anweisung selbst, allgemeinverständlich beschrieben werden.

Namensgebung von Bezeichnern

Als Faustregel gilt: Die Länge eines Bezeichners soll proportional zu seinem Sichtbarkeitsbereich sein. Für eine lokale Schleife darf die Laufvariable durchaus "i" heißen, für ein umfangreicheres Modul sollte eine relevante Variable jedoch einen aussagefähigeren Namen, wie z.B. "PersonalNr" erhalten. Zusätzlich ist bei der Deklaration ein Kurzkommentar zum Einsatzzweck der Variablen vorzusehen.

Programmtest

Zur Beschreibung eines Programmtests gehört eine Auflistung der Testeingabedaten, der erwarteten und der errechneten Ergebnisdaten. Bei Abweichungen sind Begründungen anzugeben und das Programm entsprechend zu beurteilen (z.B. "Eine Ungenauigkeit von 0.005 % ergibt sich aus dem numerischen Darstellungsbereich des Datentyps XYZ und ist f7uuml;r die erwarteten Werte vertretbar."). Grundlage der Auswahl der Testdaten ist der WHITE-BOX-Test, der gewährleistet, daß alle Programmteile durchlaufen werden. Die Auswahl der verwendeten Testdaten ist zu begründen, z.B. Indexwerte 99, 100 und 101, um bei einem Array von 100 Werten die Grenzüberschreitung zu prüfen. Die Aufführung der errechneten Ergebnisdaten sollte, mindestens teilweise, in Form von Hardcopys erfolgen.

Aufbau von Protokolltabellen

Die nachfolgenden Tabellen sind als Beispiel für einen möglichen Aufbau gedacht und nicht als festgelegte Formulare. Sie sind je nach Bedarf abzuwandeln bzw. zu ergänzen.

Modulschnittstellentabelle

Tabelle wurde mit Netscape Navigator Tags erstellt

Modulschnittstelle
Modulname:---
Funktion:
---
Parameter: In / Out Typ: Bedeutung:
------------
Voraussetzungen für den Aufruf
---
Globale Zugriffe
Lesend:--- Verändernd:---
Begründung
---

Eigenschaften der Ergebnisse
---

Fehlerfälle Fehleraktionen
------
------
------
------

Dateibeschreibungstabelle

Tabelle wurde mit Netscape Navigator Tags erstellt

Dateibeschreibung
Physikalischer Dateiname:---
Organisationsform:---
Schlüssel:---
Feldbeschreibung für die Datei
Nummer:---Feldname---Typ---
Länge
von--- bis---
Bemerkung

Seitenanfang
 © FH Wedel 21.06.2001