Richtlinien Programmierpraktika

Inhaltsverzeichnis


Einleitung

Die Erstellung einer Dokumentation für das Programmierpraktikum oder die Seminaraufgabe ist ein wesentlicher Teil der jeweiligen Leistung. Die Qualität der Dokumentation beeinflusst 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. Oktober 2008 in Kraft und sind für alle Schüler/-innen und Studenten/-innen verbindlich. Änderungen und/oder Ergänzungen zu dieser Version werden auf dieser Seite veröffentlicht.


Formale Anforderungen

Die Dokumentation ist in einem DIN A4-Schnellhefter abzugeben. Dabei ist auf ausreichende Heft- und Korrekturränder zu achten. 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 (z.B. CD, Diskette) abzugegeben. 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 Mehrbenutzersystemen erstellt wurden, sind die BenutzerID und alle erforderlichen Kennworte anzugeben. Die Abgabe von Datenträgern entfällt hierbei.


Aufbau der Dokumentation

Deckblatt

Das Deckblatt soll alle Daten enthalten, die zur Identifizierung von Programm und Ersteller/in notwendig sind. Dieses sind im einzelnen:

  • Name, Matrikelnummer, Fachbereich, Fachsemester
  • Fach- bzw. Aufgabenbezeichnung
  • Programmname, Thema

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 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 sein müssen etc. Es ist zu bedenken, daß die Ablaufbedingungen normalerweise von der Entwicklungskonfiguration abweichen.

Programminstallation und Programmstart

Welche Kommandos / Aktionen 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 Installer 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 Screenshots 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?

Programmierhandbuch

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. Hier finden sich Eure Überlegungen, die Ihr vor dem Schreiben der 1. Codezeile gemacht habt, also z.B. ob Datenstruktur1 oder Datenstruktur2 besser zum gegebenen Problem paßt und warum dies so ist, welche Algorithmen zur Problemlösung möglich sind und welcher davon warum umgesetzt wurde usw.

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.

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.

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 fü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.

Hinweise zur Inline-Kommentierung

 

Kommentare

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

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

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.

Beschreibung der Schnittstellen

Die folgenden Beschreibungen sollten Inline erfolgen. Besteht eine Unterteilung in Interface- und Implementation-Teil, so erfolgt die Modulbeschreibung im Interface, während die Beschreibung der Methoden (Funktionen und Prozeduren) in die Implementation gehört.

Beschreibung der Module

Hier ist eine Beschreibung des Moduls als Black Box gefordert. Dies kann am besten in Form einer Tabelle erfolgen (vgl. Modulschnittstelle). Folgende Angaben sollten vorhanden sein:

  • Modulname
  • Kurzbeschreibung in wenigen aussagefähigen Sätzen
  • Ersteller

Beschreibung der Methoden

Diese Beschreibung gehört bei Hochsprachen in den Kopf jeder einzelnen Methode. 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.


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.

Modulschnittstelle

Modulschnittstelle
Modulname:
---
Funktion:
---
Ersteller
---

Methodenschnittstelle

Methodenschnittstelle
Funktion:
---
Parameter: In / Out Typ: Bedeutung:
------------
Globale Zugriffe
Lesend:--- Verändernd:---
Begründung
---
Rückgabe
---
Änderungen
---

Stand: 18. September 2008, (ne)