Einführung Softwaretechnik
Checklisten für Dokumente

Sind Gruppennummer und Datum/Version aufgeführt?

• Das Datum und/oder die Version (automatisch aktualisiert) brauchen Sie, um verschiedene Fassungen Ihres Dokuments auseinanderzuhalten.

Sind alle Beteiligten aufgeführt?

• Bitte führen Sie auf dem Deckblatt die Namen, Vornamen und e-mail-Adressen aller Gruppenmitglieder an.
• Führen Sie auch an, wer für welche Phase verantwortlich zeichnet.

Sind Seiten, Abschnitte und Abbildungen nummeriert?

• Ohne Nummern wird es Ihnen schwerfallen, auf einzelne Teile Bezug zu nehmen.

Gibt es ein Dokument?

• Alle Unterlagen sollen stets als ein einzelnes druckfähiges PDF-Dokument vorliegen (und nicht etwa als eine Sammlung verschiedener Quellen).

Ist das Dokument gegengelesen?

• Haben alle Gruppenmitglieder das Dokument gegengelesen?

Ist das Dokument auf Rechtschreibfehler geprüft?

• Dies geschieht wenigstens mit entsprechenden Prüfprogrammen (ispell für LaTeX, Rechtschreibprüfung in Word).

Ist das Dokument technisch lesbar?

• Sowohl am Bildschirm als auch in ausgedruckter Form muss das Dokument ohne weitere Hilfsmittel (Lupen o.ä.) lesbar sein.

Ist das Dokument eingereicht?

• Senden Sie das Dokument im PDF-Format an <sodepra-dokumente@st.cs.uni-saarland.de>.
• Geben Sie im Betreff (Subject:) die Art des Dokuments und Ihre Gruppennummer an - z.B. "Grobentwurf Gruppe 10b".
• Senden Sie eine Kopie (Cc:) an Ihren Kunden.

Sind alle Anforderungen gemäss Skript aufgeführt?

• Siehe hierzu den typischen Aufbau eines Pflichtenhefts, wie in der Vorlesung beschrieben:

  1 Zielbestimmung
  2 Produkt-Einsatz
  3 Produkt-Umgebung
  4 Produkt-Funktionen
  5 Produkt-Daten
  6 Produkt-Leistungen
  7 Benutzungsoberfläche
  8 Qualitäts-Zielbestimmung
  9 Testszenarien
  10 Entwicklungs-Umgebung
  11 Ergänzungen
  

• Wenn Sie von der Beispiel-Gliederung abweichen, müssen Sie dies begründen.

Sind Hauptfunktionen, Daten, Leistungen gekennzeichnet?

• Balzert schlägt vor,
  • die Anforderungen (Produkt-Funktionen) mit /F10/, /F20/, usw. zu kennzeichnen,
  • die persistenten Daten mit /D10/, /D20/, usw.
  • die Leistungen bezüglich Zeit und Umfang mit /L10/, /L20/, usw.
  • die Testfälle mit /T10/, /T20/, usw.
  Dies ist wichtig, um sich in späteren Dokumenten darauf beziehen zu können.

Sind Entscheidungen nachvollziehbar?

• Sie sollten, soweit möglich, Ihre Entscheidungen begründen. Das geschieht, indem Sie Alternativen aufzählen und beschreiben, wie Sie zu Ihrer Entscheidung gekommen sind.

Werden geeignete Modellierungsverfahren eingesetzt?

• Alle zentralen Aspekte des Systems müssen präzise modelliert sein (vgl. Produktmodellierung)

Ist die Verwendung externer Ressourcen dokumentiert?

• Hierzu gehören Formate von Eingabedateien, Protokolle, Interaktion mit externen Programmen und ähnliches.

Ist die Systemevolution berücksichtigt?

• Hierunter fällt, was sich in Zukunft ändern könnte.

Decken die Testfälle die Anforderungen ab?

• Jede Anforderung muss (durch einen Testfall) validierbar sein. Bitte dokumentieren Sie explizit, welche Testfälle (/T100/...) welche Anforderungen (/F100/...) abdecken.

Gibt es ein Glossar?

• Das Glossar soll alle wesentlichen Begriffe der Aufgabenstellung präzisieren.
• Begriffe im Glossar sind als solche zu verwenden -- d.h. keine Synonyme, auch nicht zu stilistischen Zwecken.
• Das Glossar sollte nach Stichworten alphabetisch sortiert sein.

Gibt es einen Index?

• Bei umfangreichen Dokumenten ist ein Index (am Ende des Dokuments) hilfreich.

Kann man leicht durch das Handbuch navigieren?

Sind Kapitel und Abschnitte nach Benutzerzielen organisiert und benannt?
Ist das Inhaltsverzeichnis gut gegliedert?
Enthält das Stichwortverzeichnis Benutzerziele und Funktionsnamen?

Unterstützt das Handbuch leichtes Erlernen?

Richtet sich die Sprache an den Endanwender?
Wird die Information in kleinen Einheiten dargeboten?
Wird die Information in einer logischen Sequenz dargeboten?
Gibt es Beispiele? Zeichnungen? Grafiken?
Werden visuelle Kennzeichen (Typographie) konsistent verwendet?
Wird eine "Vermenschlichung" des Computers vermieden?

Ist das Handbuch gut lesbar?

• Lesbarkeit wird insbesondere erreicht
  • durch großzügigen Gebrauch von Leerraum
  • durch Vermeiden von unnötigem Jargon

Sind die Pflichtteile enthalten?

Vorwort
Inhaltsverzeichnis
Einführung
Installation
Benutzungsoberfläche
Produktstruktur
Trainingsteil
Referenzteil
Behandlung von Problemen
Literaturverzeichnis
Abkürzungsverzeichnis
Glossar
Stichwortverzeichnis / Index / Register

Gibt es geeignete Szenarien?

• Benutzer-Leitfaden und Trainings-Handbuch müssen typische Szenarien im Umgang mit dem System enthalten, und beschreiben, wie sich das System verhält.
• Diese Szenarien bilden die Grundlage für spätere Tests (und sollten deshalb einzeln gekennzeichnet sein).

Ist eine Hilfefunktion vorhanden?

• Das System sollte zumindest eine statische, passive, uniforme Hilfe anbieten.

Ist das Produkt enthalten?

• In der endgültigen Fassung machen Sie das Produkt für den Anwender verfügbar (z.B. auf einer Webseite oder einer CD)

Sind alle Anforderungen gemäss Skript aufgeführt?

• Objekt-Modell:
  Welche Objekte benötigen wir?
  Welche Merkmale besitzen diese Objekte? (Attribute, Methoden)
  Wie lassen sich diese Objekte klassifizieren? (Klassenhierarchie)
  Welche Assoziationen bestehen zwischen den Klassen?

• Sequenzdiagramm:
  Wie wirken die Objekte global zusammen?

• Zustandsdiagramm:
  In welchen Zuständen befinden sich die Objekte?

Sind alle Klassen angegeben?

• Im Objektmodell müssen alle Klassen samt ihren Assoziationen angegeben sein. Geben Sie auch einen kurzen Text an, der die Rolle der Klasse beschreibt.

Sind alle Attribute und Methoden angegeben?

• Geben Sie im Objektmodell für jede Klasse alle Attribute und Methoden (samt Parametern) an.

Sind alle Assoziationen angegeben?

• Geben Sie im Objektmodell Assoziationen gemäss UML mit Multiplizitäten, Aggregation/Komposition an.

Entsprechen die Klassen zentralen Konzepten der Aufgabenstellung?

• Wichtige Hauptworte der Aufgabenstellung sollten als Klassen im Entwurf auftauchen.
• Vorsicht ist angebracht bei Klassen, deren Namen Verben sind; typischerweise sind Aktionen als Methoden besser modelliert.

Entsprechen die Methoden zentralen Konzepten der Aufgabenstellung?

• Wichtige Verben der Aufgabenstellung sollten als Methoden im Entwurf auftauchen.
• Vorsicht ist angebracht bei Methoden, deren Namen Hauptworte sind und etwas anderes tun als eine entsprechende Klasse zurückliefern.

Sind die Namen aussagekräftig?

• Vermeiden Sie generische Namen wie "Converter", "Parser", "Main", "do_it()"
• Benutzen Sie stattdessen spezifische Namen wie "XMLGenerator", "DTDParser", "MyTool", "resolve_polynom()"

Sind die Grundprinzipien der Zerlegung erfüllt?

Separation der Interessen:

Hohe Kohäsion: Module sollten logisch zusammengehörende Funktionen enthalten
Wenige Schnittstellen: Module sollten mit möglichst wenig anderen Modulen kommunizieren
Schwache Kopplung: Module sollten so wenig Information wie möglich austauschen

Abstraktion: Wurde die allgemeinste Lösung für das Problem gesucht?
Evolutionsfähigkeit: Sind Eigenschaften, die sich absehbar ändern, in spezifischen Komponenten isoliert?

Ist das dynamische Verhalten beschrieben?

• Für jeden Testfall im Pflichtenheft geben Sie wenigstens ein Sequenzdiagramm an, das das dynamische Verhalten im Testfall beschreibt.
• Jedes Sequenzdiagramm umfasst
  alle beteiligten Methoden
  aller beteiligten Objekte
  sowie zentrale Daten, die dabei ausgetauscht werden
• Prüfen Sie Ihre Methodenaufrufe:
  Für jeden Aufruf muss es eine Rückkehr geben.
  Stimmen die Steuerungsfoki? (welches Objekt ist wann aktiv?)
  Stimmen die Lebenslinien? (welches Objekt existiert wann?)

Decken die Sequenzdiagramme alle Klassen ab?

• Jede Klasse muss wenigstens einmal in einem Sequenzdiagramm auftreten.

Sind die Diagramme lesbar?

• In der Regel passt der gesamte Entwurf nicht lesbar auf eine Seite. Gehen Sie deshalb wie folgt vor:
  • Machen Sie ein Gesamt-Modell, in dem Klassen ohne Attribute und Methoden dargestellt sind (um Platz zu sparen)
  • Stellen Sie Subsysteme mit allen Details in eigenen Abbildungen vor.

Sind Entscheidungen nachvollziehbar?

• Sie sollten, soweit möglich, Ihre Entscheidungen begründen. Das geschieht, indem Sie Alternativen aufzählen und beschreiben, wie Sie zu Ihrer Entscheidung gekommen sind.

Ist der Grobentwurf als Arbeitsgrundlage geeignet?

• Jedes Mitglied Ihrer Gruppe muss in der Lage sein, einzig auf Grundlage des Grobentwurfs allein das komplette Produkt zu erstellen.
• Lassen Sie jedes Mitglied prüfen, ob diese Bedingung gegeben ist.

Sind Testfälle gekennzeichnet?

• Analog zu Balzert können Sie die Testfälle mit /S100/, /S110/, usw. kennzeichnen.

Sind die Testfälle übersetzbar?

• Die Testfälle sollten der Syntax und Semantik der für das Projekt verwendeten Programmiersprache entsprechen.
• Hierzu gehört auch, dass Sie alle Variablen und Parameter korrekt definieren und durchreichen.

Sind die erwarteten Ergebnisse dokumentiert?

• Dies geschieht gewöhnlich mit Hilfe von Zusicherungen.
• Das wenigste, was man erwarten kann, ist, dass das Test-Ende erreicht wird, dokumentiert mit assert(true).

Laufen die Tests automatisch ab?

• Dies geschieht gewöhnlich mit Hilfe von JUnit oder CPPUnit.

Entsprechen die Tests den Szenarien im Grobentwurf?

• Die Tests sollen die im Grobentwurf beschriebenen dynamischen Modelle (Sequenzdiagramme) verfeinern.

Entsprechen die Tests den Testszenarien im Pflichtenheft?

• Die Tests sollen den im Pflichtenheft beschriebenen Szenarien entsprechen.

Sind Entscheidungen nachvollziehbar?

• Sie sollten, soweit möglich, Ihre Entscheidungen begründen. Das geschieht, indem Sie Alternativen aufzählen und beschreiben, wie Sie zu Ihrer Entscheidung gekommen sind.

Sind die Tests als Arbeitsgrundlage geeignet?

• Jedes Mitglied Ihrer Gruppe muss in der Lage sein, auf Grundlage des Grobentwurfs und der Spezifikation allein das Produkt zu erstellen. Dabei können beliebige Teile von Dritten zugeliefert und problemlos integriert werden.
• Lassen Sie jedes Mitglied prüfen, ob diese Bedingung gegeben ist.

Ist der Quellcode enthalten?

• Machen Sie den Quellcode in maschinenlesbarer Form verfügbar (z.B. auf einer Webseite oder einer CD)
• Sorgen Sie dafür, dass Programmierer Ihr Produkt aus dem Quellcode erstellen können (durch geeignete Übersetzungs- und Installations-Anweisungen)

Sind alle Abweichungen von früheren Dokumenten aufgeführt und begründet?

• Beschreiben und begründen Sie
  alle Abweichungen vom Pflichtenheft,
  alle Abweichungen vom Grobentwurf,
  alle Abweichungen von der Spezifikation.
  
• Sie können auch überarbeitete Fassungen der Dokumente integrieren; dann müssen Sie aber alle nachträglichen Änderungen hervorheben (und begründen).

Sind die Autoren aufgeführt?

Sind Entscheidungen nachvollziehbar?

• Sie sollten, soweit möglich, Ihre Entscheidungen begründen. Das geschieht, indem Sie Alternativen aufzählen und beschreiben, wie Sie zu Ihrer Entscheidung gekommen sind.

Geben Sie für jede Komponente an, von wem sie erstellt wurde.

• Jedes Teammitglied sollte an der Implementierung beteiligt sein.

Welche Tests wurden ausgeführt?

• Dies geschieht gewöhnlich per Verweis auf frühere Dokumente (Pflichtenheft, Spezifikation)

Ist die Testgüte bewertet?

Abgedeckte Funktionalität im Pflichtenheft (normal 100%)
Abgedeckte Methoden des Programms (Ziel: 100%)
wenn technisch möglich (z.B. mit "gcov"): Zweig- und Anweisungsüberdeckung (gewöhnlich weniger als 100%)

Sind die Testergebnisse beschrieben?

• Wieviele und welche Tests waren erfolgreich?
• Wieviele und welche sind fehlgeschlagen?

Welche Konsequenzen ziehen Sie aus den Testergebnissen?

• Welche Qualitätsmerkmale erfüllt Ihre Software?
• Wie weit sind die Vorgaben des Pflichtenheftes erfüllt?
• Was würden Sie wieder machen? Was anders?

Allgemeine Tips und Tricks

Benutzen Sie LaTeX.

• Da Sie in der Regel parallel an Ihren Dokumenten arbeiten werden, empfehlen wir LaTeX zum Erstellen des Entwurfs - hier lassen sich parallele Änderungen per CVS leicht integrieren und verfolgen.

Benutzen Sie Dia.

• Benutzen Sie Dia zum Erstellen Ihrer Diagramme - insbesondere der UML-Diagramme. Die Diagramme können Sie mit Dia in das EPS-Format exportieren. In LaTeX benutzen Sie folgende Befehle, um z.B. die Abbildung anmelden.eps in Ihr Dokument einzubinden:

  \usepackage{graphicx}
  ...
  \begin{figure}
  \includegraphics*[width=\textwidth]{anmelden}
  \caption{Anmelden beim Server als UML-Sequenzdiagramm}
  \label{fig:anmelden-beim-server}
  \end{figure}
  ...
  
  Das Anmelden beim Server ist in Abbildung~\ref{fig:anmelden-beim-server} 
  dargestellt.
  

  Anstelle der hier hervorgehobenen Abschnitte setzen Sie passende Titel, Texte und Größen ein.

Erzeugen Sie PDF-Dokumente.

• Sie können Ihr Dokument entweder mit LaTeX erstellen und anschliessend in PDF wandeln (mit dvips und ps2pdf oder ähnlichen Werkzeugen) oder gleich mit PDFLaTeX erzeugen. Wenn Sie PDFLaTeX benutzen, müssen Sie Ihre Abbildungen im PDF-, PNG-, oder JPG-Format erzeugen.

Benutzen Sie PostScript-Fonts.

• Mit PostScript-Fonts können Sie Ihre PDF-Dokumente besser am Bildschirm lesen:

  \usepackage{times}
  

Pflegen Sie Ihre Dokumente.

• Am Ende des Projektes geben Sie überarbeitete Fassungen der Dokumente ab, in denen der tatsächliche Projektstand beschrieben ist. Es empfiehlt sich also, die Dokumente während des Projektes stets auf dem Laufenden zu halten.

Impressum ● Datenschutzerklärung