> Projekt: Software-Sanierung > Projekt-Management > Vorgaben > Hinweise zu den Entwicklerdokumenten > Analyse und Definition

Hinweise zur Entwicklerdokumentation

Analyse und Definition
 

Dokumentversion: 1.0 (19. Dez. 2000)
Autor:           Erstautor: U.Sacklowski, Fortschreibung durch projekt98, projekt99
Zustand:   in Bearbeitung

Diese Dokumentation ist bei Bedarf/Erkenntnis durch die Projektmitglieder fortzuschreiben (mit Autorenhinweis).


 

Inhalt

1.   Analyse und Definition
1.1   Gesamtvorgang
1.2 Use Case-Diagramm
1.3  Verhaltensspezifikation und Anforderungsspezifikation (Pflichtenheft)
1.3.1   Anforderungsspezifikation (Pflichtenheft)
1.3.2   Verhaltensspezifikation
 

1.   Analyse und Definition

Die Gliederung der Analyse- und Definitionsdokumente erfolgt auf der obersten Ebene bezüglich der Anwendungsfälle (Use Cases). Die nachfolgenden Gliederungspunkte beziehen sich auf einen Anwendungsfall.

1.1 Gesamtvorgang

Die Dokumentation des Gesamtvorganges ist für komplexe Abläufe, wie sie bei der Topographie und der Diffraktometrie/Reflektometrie anzutreffen sind, sinnvoll. Innerhalb der Softwareentwicklung gehört ein solches Dokument in die Analysephase, hier als Teil des Ist-Zustandes und des Soll-Konzeptes.

Als Beispiel für ein Gesamtvorgang-Dokument sei verwiesen auf die Topographie: (IX. Entwicklerdokumentation; Analyse und Definition; Topographie).

Inhalt dieses Dokumentes:
1.      Einleitung: Fachlicher Hintergrund, Ziel und Grobablauf des Topographie-Gesamtvorganges
2.      Feinablauf des Topographie-Gesamtvorganges
2.1      Verbale Beschreibung    (eine weitere Untergliederung erfolgt dort)
2.2      Beschreibung in Pseudokode

Bemerkungen zum Gesamtvorgang:

Der Gesamtvorgang wird in Teilvorgänge gegliedert. Ihrer Realisierung dienen:
- Manuelle Aufgaben, d.h. Aufgaben ohne Unterstützung des RTK-Steuerprogrammes (z.B. handschriftlicher Eintrag in das Protokollbuch),
- Dialog-Aufgaben, d.h. Aufgaben mit Unterstützung des RTK-Steuerprogrammes (z.B. bei der manuellen Justage, wo sich Eingaben in eine Dialogbox durch den Nutzer mit der durch das RTK-Steuerprogramm gesteuerten Regelung abwechseln oder im Zählerfenster die Anzeige der aktuellen Zählraten).

Dialogaufgaben stellen Anforderungen an das RTK-Steuerprogramm dar. Sie sind in der Definition, z.B. im Pflichtenheft, weiter zu spezifizieren.

Die Beschreibung des Feinablaufes des Topographie-Gesamtvorganges erfolgt einmal verbal, hier ausführlich und im Falle von Dialogaufgaben mit den entsprechenden Dialogboxen und Dialogfenstern, und zum anderen in Pseudocode. Letztere Darstellung ist kompakt und soll den Zugang zum Ablauf des Gesamtvorganges erleichtern. (Dieser Vorschlag stammt von eine Gruppe aus dem Projekt99-Seminar. Seine Zweckmäßigkeit bleibt zu diskutieren.)

Zum Pseudocode:

Verwendete Konstrukte: (nach R.Dumke: Modernes Software Engineering, Vieweg 1993, S.15)
 
Sequenz

A   seq
       B
       C
A   end

 Selektion

A
     select   bedg1
          B | leer
     or   bedg2
          C | leer
A end

 Iteration

A
     iter while   bedg
          B
A   end

 Iteration

A
     iter until   bedg
          B
A   end

zusätzlich:   ||   Parallelität

Wörter einer lexikalischen Einheit werden mit '_' oder '-' verbunden
kursiv-fett: use_case
kursiv: Titel von DB und DF
     DB: Dialogbox
     DF: Dialogfenster

MA: Manuelle Aufgabe
DA: Dialog-Aufgabe

Bsp. zum Pseudocode aus dem Topographie-Dokument:

Topographie_Gesamtvorgang   seq

     Erfassung_allgemeiner_Angaben_zum_Meßvorgang seq
          Handschriftliche_Einträge_in_einem_Protokollbuch (MA)
          Allgemeine_Einstellungen_zum_Meßvorgang (DA)
          /* DB: Allgemeine Einstellungen */
     Erfassung_allgemeiner_Angaben_zum_Meßvorgang end

     Platzierung_der_Probe_auf_dem_Probenteller_und_Vorabjustage seq
          .....

1.2 Use Case-Diagramm

Erstellung eines Use Case-Diagrammes für diesen Anwendungsfall. Dieses Use Case-Diagramm wird unter dem Punkt 'IX. Entwicklerdokumente; Analyse und Definition; Use Case-Diagramme' eingebunden. Hier erfolgt nur ein Link auf dieses Dokument. Gibt es kein Use Case-Diagramm, so steht unter diesem Punkt 'entfällt'.

Es ist zu prüfen, ob ein Use Case-Diagramm für den einzelnen Anwendungsfall sinnvoll ist, oder ob das Use Case-Diagramm für das gesamte System genügt (siehe: 'IX. Entwicklerdokumente; Analyse und Definition; Use Case-Diagramme; RTK-Projekt').

1.3 Verhaltensspezifikation und Anforderungsspezifikation (Pflichtenheft)

Bei der Erarbeitung eines Pflichtenheftes innerhalb des Reverse Engineering ergeben sich im Detail zahlreiche Probleme. Die Problemlösung führt uns zu zwei unterschiedlichen Dokumenten:
 

Im Detail diskutiert ist diese Problematik im Dokument Doc_Anal_Def.ps.
 

1.3.1 Anforderungsspezifikation (Pflichtenheft)

Für die Gliederung von Pflichtenheften findet man in der Literatur und in den Dokumentationen zu Case-Tools zahlreiche Hinweise. Wir orientieren uns an der von Balzert empfohlenen Gliederung (H. Balzert: Lehrbuch der Softwaretechnik: Softwareentwicklung; Berlin, Oxford: Spektrum, Akad. Verlag, 1996, S. 106 f). Diese ist allerdings recht ausführlich.

Orientiert an dieser Gliederung haben sich Sebastian Lühnsdorf und Alexander Schad in Ihrem Pflichtenheft zur 'Einbindung 2-dimensionaler Detektoren in das RTK-Steureprogramm' (siehe: IX. Entwicklerdokumente, Analyse und Definition, Detektoren, 2-dimensionale Detektoren). Ob die Gliederung überdimensioniert ist, bleibt zu diskutieren bzw. sollten Erfahrungen zeigen.

1.3.2 Verhaltensspezifikation

Die Gliederung ist auf der letzten Seite des Dokumentes Doc_Anal_Def.ps beschrieben. Genau mit dieser Gliederung existiert noch kein Dokument.
Unsere bisherige Gliederung ist jedoch weitestgehend identisch, so daß im Wesentlichen nur einige Umstrukturierungen vorgenommen werden müssen.

Änderungen gegenüber der alten Gliederung:

- Benutzerschnittstelle und Dateien werden zu einem Punkt vereinigt
- Pkt. Testfälle entfällt. Testfälle werden dokumentiert unter 'Entwicklerdokumente, Test'.
- Fehler und Änderungswünsche sind getrennte Punkte
- neuer Pkt.: 7.   Verwandte Dokumente
- neuer Pkt.: 8.   Änderungen am Dokument
- neuer Pkt.: 9.   Quellen des Dokuments
- neuer Pkt.: 10.   Glossar

Nachfolgend wird die neue Gliederung erläutert. Ergänzend für ein tieferes Verständnis zu einzelnen Punkten können die bisherigen Dokumente zur 'Topographie' und zur 'Manuellen Justage' genommen werden. Siehe:
- IX. Entwicklerdokumente, Analyse und Definition, Topographie, Einst. der Parameter für die Topographie (neue Version),
- IX. Entwicklerdokumente, Analyse und Definition, Topographie, Start und Kontrolle der Topographie (neue Version),
- IX. Entwicklerdokumente, Analyse und Definition, Man./Autom. Justage, Probe u. Kollim. manuell einstellen (K. Bothe).

In Kürze wird sich auch das Dokument 'IX. Entwicklerdokumente, Analyse und Definition, Diffraktometrie/Reflektometrie, LineScan' anbieten, dies dann vollständig nach der neuen Gliederung.

Dokumentationskopf und Gliederung

a) Dokumentationskopf
     als Beispiel siehe  'IX. Entwicklerdokumente, Analyse und Definition, Diffraktometrie/Reflektometrie, LineScan'
     im Detail:
     - Funktion: wie z.B. bei der Manuellen Justage oder
     - Hauptfunktion, Teilfunktion: wie z.B. bei der Diffraktometrie/Reflektometrie, LineScan
     - Dokumentversion: 1.0, 1.1, ...; nur bei bedeutenden Änderungen 1. -> 2. usw.
     - Autor(en):
     - Änderungen: kurze Beschreibung bzgl. Vorgängerversion (2-3 Sätze). Vollständig in Pkt. 8.
     - Zustand: in Bearbeitung / abgeschlossen

b) Gliederung

1.   Überblick
2.   Funktionale Beschreibung
3.   Daten
3.1  Benutzerschnittstelle(n)
            Dialogbox
3.1.1   Steuerung
3.1.2   Eingaben/Ausgaben und Prüfung
       -> bei einer Benutzerschnittstelle sollte man diese Gliederung  so nehmen
       -> bei mehreren Benutzerschnittstellen sind diese unter 3.1.1 - 3.1.i zu dokumentieren
3.2  Dateien
4.1   .ini-Datei
4.2  - 4.i    weitere Dateien, z.B. mak-, log- und Messwerte-Datei
4.   Fehler
5.   Änderungswünsche
6.   Offene Fragen
7.   Verwandte Dokumente
8.   Änderungen am Dokument
9.   Quellen des Dokuments
10.   Glossar

Bemerkungen zur Gliederung:

2. Funktionale Beschreibung
Falls ein Dokument zum Gesamtvorgang existiert, sind Redundanzen mit der entsprechenden Dialogaufgabe des Gesamtvorganges gegeben. Die Beschreibung hier sollte detaillierter erfolgen. Wichtig ist, daß Konsistenz gewahrt wird, d.h., die Teilfunktionen sollten dort wie hier die gleichen sein.

Ein Voranstellen der/des entsprechenden Dialogbox/Dialogfensters dient dem Verständins der funktionalen Beschreibung.

Bereits hier beschriebene Fehler, Wünsche und Fragen sind eindeutig zu kennzeichnen mit:
#Fehler:
#Wunsch:
#Frage:
Diese sind zusätzlich in die Punkte 4., 5., 6. aufzunehmen.

3.1 Benutzerschnittstelle:
Zu beschreiben ist die grafische Ein/Ausgabe (Dialogboxen, Fenster zur Anzeige von Meßergabnissen
(StepScan, AreaScan).

3.1.1 Steuerung
siehe beispielhaft: 'IX. Entwicklerdokumente, Analyse und Definition, Diffraktometrie/Reflektometrie, LineScan'

3.1.2 Eingaben/Ausgaben und Prüfung
Zu jedem Dialogelement sind anzugeben:

3.2   Dateien
Bei unserem System zählen hierzu die Dateien  .mak-, .ini-, Log- und Meßwert-Dateien. Sie sind hier mit ihren wesentlichen Bestandteilen zu beschreiben. Details fallen in das Design. Des weiteren scheinen Dateibeziehungen nicht zu existieren, so daß entsprechende Beschreibungsmittel, wie ER-Diagramm, nicht erforderlich sind.

4.   Fehler
Alle Fehler sind tabellarisch unter 'Entwicklerdokumente, Fehler, Fehler je Anwendungsfall' zu dokumentieren. Hier erfolgt nur ein Link dorthin.

5.   Änderungswünsche
Änderungswünsche sind hier zu nennen. Bei ihrer Realisierung sind sie hier funktional und datenmäßig zu beschreiben. Des weiteren ist ein evtl. vorhandener Gesamtvorgang fortzuschreiben.

6. Offene Fragen
zum Dokument (zur Funktionsweise des Systems)
(Beispiele hierfür siehe: Pflichtenheft zur 'Probe und Kollimator manuell einstellen'.)

7.   Verwandte Dokumente
vorausgesetzte, weiterführende, ergänzende Dokumente

8.   Änderungen am Dokument
Detaillierte Beschreibung aller Änderungen bezüglich aller Vorversionen (Fortschreibung).

9.   Quellen des Dokuments
Treffen mit Physikern: Termine und Personen
Diskussion mit ...
andere Dokumente
äußeres Verhalten
Programmquellen
...

10.   Glossar
Vollständig für dieses Dokument. Ein Hochziehen aller Glossare erfolgt unter 'Entwicklerdokumente, Analyse und Definition, Glossar'