Implementationsbeschreibung

Komponente: Diffraktometrie/Reflektometrie Ablauf und Einstellungen
Jens Ullrich, Stephan Berndt
Status: fertig

Gliederung

1. Einleitung
2. Ausgangssituation
3. Fehler
4. Kommentierung der Quellen
5. Formatierung der Quellen mit 'astyle'
6. Erweiterungen

1. Einleitung

Der folgende Abschnitt dieses Dokument stellt den vorgefundenen Zustand der Quellen dar. Sie werden auf das Vorkommen von totem Code, die Wahl der Bezeichner sowie die vorgefundene Kommentierung hin untersucht. Im dritten Kapitel werden die Fehler bezüglich ihres Auffindens und ihrer Art näher untersucht. Im folgenden Abschnitt wird das Vorgehen bei der Kommentierung beschrieben und welche Werkzeuge dazu benutzt wurden. Der fünfte Teil beschäftigt sich mit der Formatierung der Quellen mit 'astyle' bzgl. unserer Projekt-Vereinbarungen. Im letzten Abschnitt geht es um die vorgenommenen Erweiterungen mit einer tabellarischen Darstellung zum Umfang der hinzugekommenen, entfernten bzw. veränderten Quelltextzeilen.

Der Gesamtumfang der zu kommentierenden Quellen lag bei ca. 6000 Quelltextzeilen. Die vorgefundenen Quellen sollten in ihrer Funktionalität nicht verändert werden, auch vorhandene Kommentare sollten erhalten bleiben. Sofern sie nicht aussagekräftig waren, sollten sie auskommentiert werden und durch einen eigenen Kommentar ersetzt werden. Die Kommentierung umfaßte die folgenden Dateien:

2. Ausgangssituation

Toter Code

Die kommentierten Quellen enthalten mehr als 300 LOC toten Code.

Die folgende Tabelle enthält implementierte Methoden, die nicht benutzt werden.

Weiterhin gibt es Quellcode-Abschnitte, die nur durchlaufen werden, wenn eine Variable einen bestimmten Wert annimmt, sie diesen Wert aber nie annimmmt. Der folgende Abschnitt aus der Datei m_arscan.cpp zeigt einen case-Zweig, der nicht durchlaufen wird. Die Variable eSaveFormat nimmt den Wert ShiftedStandard nie an. In diesem Beispiel sind das 36 LOC toter Code.

  switch ( eSaveFormat )
  {
                //! fehler (nur Standard moeglich)
         case ShiftedStandard:
                // 1. Scan ist noch nicht mit gueltigen Daten belegt
                if ( bSaveContinuous && ( 1 == lpDBase->GetCNumber() ) )
                  break;
                buf = new char [ 8 * 3000 ];
                for ( nCIdx = 0; nCIdx < lpDBase->GetCNumber(); nCIdx++ )
                {
                  sprintf( buf, "Scan %d von %d schreiben.", nCIdx + 1,
                                lpDBase->GetCNumber() );
                  SetInfo( buf );
                  TheCurve = lpDBase->GetCurve( nCIdx );
                  TheCurve->SetPP( 0 );
                  TheCurve->FastOpen();
                  numbercolumn = GetAdditionalColumns() + MainCurve->GetPNumber();
                  for ( idx = 0; idx < numbercolumn; idx++ )
                  {
                         if ( GetShift( nCIdx ) <= idx )
                                if ( TheCurve->FastPGet( d0, fIntensity, d2 ) )
                                  if ( 0.0 != fIntensity )
                                  {
                                         short pp = 3 - log10( fIntensity );
                                         strcpy( fmt, "%.3f " );
                                         if ( pp < 0 ) pp = 0;
                                         fmt[ 2 ] = ( char ) ( '0' + pp );
                                         sprintf( buf, fmt, fIntensity );
                                         goto Ready2;
                                  }
                         sprintf( buf, "0 " );
Ready2:
                         _lwrite( hFile, ( LPSTR ) buf, strlen( buf ) );
                  }
                  TheCurve->FastClose();
                  strcpy( buf, EOL );
                  _lwrite( hFile, ( LPSTR ) buf, strlen( buf ) );
                }
                delete[] buf;
                break;

Bezeichner

Die Wahl der Bezeichner für die Klassen, ihre Methoden und Attribute sind meistens aussagekräftig und mitunter hilfreich beim Verstehen der Quellen. Bei Attributen ist meist ein Buchstabe vorangestellt, der den Typ verdeutlicht, z.B. ist bFileChanged eine Bool'sche Variable. Die Bezeichnungen der Klassen-Methoden geben meist schon einen Hinweis auf ihre Funktion, z.B. rButtonDown für das Kommando 'Rechte Maustaste gedrückt' oder UpdateFile aktualisiert die Datei mit dem gerade verwendeten Dateinamen. Es werden durchweg englischsprachige Bezeichnungen gewählt.

Kommentare

Die Quellen enthalten so gut wie keine Kommentare. Die vorhandenen Kommentare sind für das Verstehen der Quellen oft unbrauchbar. Die Kommentare sind verschiedensprachlich gehalten. Es gibt sowohl englischsprachige als auch deutschsprachige Kommentare.

Weitere Bemerkungen

3. Fehler

Je komplexer ein Programm ist, desto fehleranfälliger ist es. Dies bestätigt sich auch beim XCTL-Programm.
Schon aufgrund der starken Interaktion mit fast allen Softwarekomponenten (wie Motoren, Detektoren, Steuerung ,Darstellung ...) trifft das auf den Programmteil 'Diffraktometrie/Reflektometrie' besonders zu.
Die vollständige Fehlerliste zum Use-Case 'Diffraktometrie/Reflektometrie' ist hier zu finden.

Welche Arten von Fehlern wurden gefunden?

Die vorgefundenen Fehler lassen sich in verschiedene Kategorien einordnen. Da wäre zum einen die Kategorie von Fehlern, die aus fehlerhaften Eingaben in den diversen Dialogen resultiert. Dieser häufig auftretende Fehler war einfach zu finden und relativ leicht zu beheben, da die Überprüfung der Dialogeingaben zumeist in der Methode ‚CanClose’ der jeweiligen Dialogboxklassen stattfindet.
Diese Fehler wurden zu einem frühen Zeitpunkt entdeckt und korrigiert, um auch die Anzahl der Folgefehler zu verringern.
Eine weitere Kategorie bilden die Fehler, die mit dem Speichern bzw. Nachladen von Werten zu tun haben. Dabei reichen die Fehler vom unterlassenen Einlesen wichtiger Parameter bis zum Benutzen von Dateizugriffsmethoden beim Speichern und Nachla-den, die nicht vollständig miteinander kompatibel sind.

Eine weitere größere Kategorie sind die Fehler, die mit dem eigentlichen Scanvorgang zu tun haben. Auf diesem Gebiet gibt es aber auch zahlreiche Vermischungen und Überschneidungen mit anderen Gebieten (Speichern, Darstellung, usw.). Grundsätzlich kann man sagen, daß die Fehler aus diesem Gebiet am schwierigsten aufzudecken und deren Ursachen sehr schwer zu lokalisieren waren. Grund dafür ist unter anderem die starke Interaktion zwischen den Klassen sowie das verstärkte Versenden von Komman-dos  zwischen den Komponenten und dem daraus resultierenden, sehr schwer nachvoll-ziehbaren Programmablauf. Aber auch der Zugriff auf Motoren, Detektoren und weitere Komponenten erschwerte die Lokalisierung von Fehlerursachen in diesem Gebiet. So trat häufiger das Problem auf, das für einen uns mitgeteilten Fehler nicht alle Vorbe-dingungen bekannt waren und so das Reproduzieren des Fehlers auf Anhieb nicht möglich war.

Wie wurden die Fehler gefunden?

Die meisten Fehler sind während des Prozesses der Einarbeitung in die Quellen durch Tests mit Hilfe der simulierten Hardware gefunden worden. In diesem Zusammenhang waren die Möglichkeiten der Simulation von Hardware (siehe Kapitel 6.1) von enormem Vorteil für das Auffinden, Lokalisieren und Reproduzieren von Fehlern.
Auf Fehler wurden wir aber auch von den Physikern bzw. anderen Projektgruppen aufmerksam gemacht (z.B. Frau Richter, Herr Panzner).
Beim Auffinden der Fehler gab es 2 unterschiedliche Vorgehensweisen. Im Falle eines uns bekannten Fehlers, der uns mitgeteilt wurde bzw. der uns bei Simulationen aufgefallen war, wurde dieser über den gerade aktiven Quelltext zurück verfolgt und so der Fehler im Quelltext lokalisiert. Dieses Vorgehen war aber z.B. bei Folgefehlern oder Seiteneffekten wegen der problematischen Reproduzierbarkeit sehr aufwendig.
Ein zweites Vorgehen war das Auffinden und Beheben von offensichtlichen Fehlern während der Phase der Einarbeitung und Kommentierung der Quellen. In dieser Phase wurde jede Funktion und Methode aller für unseren Use-Case wichtigen Klassen be-trachtet, nachvollzogen und kommentiert, so daß in diesem Zusammenhang auch Fehler in der Programmierung auffielen. Die Art der Fehler, die hierbei gefunden wurden, waren also eher auf schlechten Programmierstil zurückzuführen und weniger auf Fehler in der Umsetzung der Wünsche der Physiker in das Programm.

Zu welchem Zeitpunkt wurden Fehler gefunden?

Ein großer Teil der Fehler wurde zu einem frühen Zeitpunkt während der Phase der Ein-arbeitung in die Quellen bzw. die Kommentierung der Quellen gefunden. Dies betrifft in besonderem Maße die Fehler, welche auf fehlende bzw. ungenügende Kontrolle der in den Dialogboxen eingegebenen Werte beruhen. Aber auch kleinere Fehler aus allen anderen Kategorien wurden gefunden. In dieser Phase wurden vor allem Fehler, die auf eine einzelne Methode oder Funktion begrenzt waren, gefunden.
Schwierigere Fehler waren solche, die auf mehrere Methoden verteilt waren bzw. erst durch die Interaktion zwischen verschiedenen Methoden zu Fehlern führten. Diese Art von Fehlern waren von uns erst zu lokalisieren, nachdem ein gewisses Verständnis für die Quellen und für die Abläufe und Interaktionen in ihnen vorhanden war. Teilweise wurden solche Fehler erst in der Phase der Programmierung der Erweiterungswünsche entdeckt, also zu einem Zeitpunkt, zu dem wir eigentlich der Meinung waren, die Fehlerbehebung abgeschlossen zu haben. Auch zum jetzigen Zeitpunkt (nach dem Ende der Implementation der Erweiterungen) kann die Fehlerbehebung nicht als abgeschlos-sen betrachtet werden.

Welche Schwierigkeiten traten auf?

Besondere Schwierigkeiten traten bei Fehlern auf, die sich nicht auf den reinen Teil der Diffraktometrie/Reflektometrie begrenzen ließen. In diesen Fällen war es teilweise nötig, sich genauer in die Methoden fremder Klassen wie z.B. ‚TMotor’ oder ‚TDevice’ einzuarbeiten. Dieser Prozess war auch durch Nachfragen und Gespräche bei den für diese Programmteile zuständigen Projektgruppen oftmals nicht zu umgehen.
Eine weitere Schwierigkeit stellte das fehlende exakte physikalische Hintergrund-wissen dar. So waren einige Fehler, die korrekt und fehlerfrei implementiert waren, erst durch Gespräche mit den Physikern als Fehler zu entlarven (z.B. Absorber).
Ungenügende Information über die genauen Vorbedingungen und Einstellungen, die zu einem Fehler führten, bilden eine weitere Schwierigkeit bei Fehlern, die uns von den Physikern oder anderen Personen mitgeteilt wurden. Um eine Fehlerursache finden zu können und außerdem die Richtigkeit der Korrektur eines Fehlers testen zu können, ist eine Reproduzierbarkeit unerlässlich. Die Fehler beruhen aber oft auf Spezialfällen, bei denen jeder veränderte Ausgangsparameter zu einem anderen Ergebnis führen kann.

Bewertung der Fehler und ihrer Ursachen:

Bei dem von uns betrachteten Quellcode entstand oft der Eindruck, daß sich das Programm noch mitten in der Entwicklungsphase befindet. Die Art der Fehler verstärkte diesen Eindruck noch, denn der Großteil der Fehler resultiert auf scheinbaren Flüchtigkeitsfehlern bzw. nur ansatzweise durchgeführter Überprüfung von Eingabe-werten. Bei anderen Funktionen (z.B. SLD-Scan) hatte man  den Eindruck, daß die Implementation vorzeitig  abgebrochen wurde, denn bei diesen Funktionen finden sich zahlreiche Fehler in allen Kategorien. Dabei sind diese Fehler oftmals so offensichtlich und in der Benutzung des Programms auch deutlich als Fehler zu identifizieren, daß man zu diesem Schluss kommen mußte, d.h. vermutlich ist entweder die Programment-wicklung mitten in der Entwicklung oder Weiterentwicklung abgebrochen worden oder der Programmierer hatte seine Methoden nicht genügend getestet.

4. Ablauf der Kommentierung

Konventionen

Folgende Konventionen waren im Rahmen des Projekts für die Kommentierung vereinbart worden (s.a. Codekonventionen)

• keine TABS und keine Umlaute in den Quellen verwenden

• Klassisches Blocklayout mit Einrückung um 2 Leerzeichen

• keine Zeile länger als 80 zeichen, wird ein Umbruch nötig, soll auf der nächsten Zeile um vier Leerzeichen eingerückt werden

• Kommentare stehen vor der kommentierten Zeile

• Kommentare so weit wie den umgebenden Code einrücken

• reichlich Leerzeichen verwenden

• Kommentare beginnen mit //!

• alten Kommentaren wird ein //! alt vorangestellt

Kommentierung

Zunächst ging es uns darum, zu verstehen, zu welchen Stellen im Programmtext bei Aufruf von bestimmten Programm-Funktionen gesprungen wird. Dazu haben wir Messagboxen in das Programm integriert, die uns fortlaufend die Stelle im Programm zeigten, an der sich das Programm gerade befand. Dadurch konnten wir schon vorab auf die Funktion der einzelnen Methoden schließen. Ebenfalls geholfen hat uns dazu aber auch die gute Wahl der Klassenbezeichnung sowie die Bezeichnung ihrer Methoden und Attribute. Ein weiteres wichtiges Werkzeug war die in die Borland-Umgebung integrierte Anwendung 'grep'. Mit ihr konnten wir leicht die Stellen im Programm finden, an denen eine Funktion implementiert ist, die uns bis dahin unbekannt war. Teilweise haben wir auch auf die Windows-Suche zurückgegriffen. Messageboxen dienten uns auch später, den Wert einiger Variablen im Verlauf des Programms auszugeben, um auf bestimmte Reaktionen des Programms schließen zu können.

5. Formatierung der Quellen mit 'astyle'

Nach Abschluß der Kommentierung waren die Quellen entsprechend den Projektvereinbarungen zu formatieren. Als Werkzeug diente hierzu das Programm astyle von Tal Davidsen. Die von uns verwendete Befehlszeile lautete:

astyle [Optionen] {Originalquelle} {Zielquelle}

Entsprechend unseren Projekt-Vereinbarungen waren die folgenden Optionen zu wählen:

Die erzielten Ergebnisse waren zufriedenstellend. Astyle fügte allerdings TABS in das Dokument ein. Es mußten demzufolge nach der Benutzung von 'astyle' alle TABS durch Leerzeichen ersetzt werden.

Eine Möglichkeit, die wir verwendeten, ist mit dem Editor nedit unter Unix mit dem Kommando Replace bei zuersetzendem Text ALT+TAB zu drücken und durch 8 Leerzeichen zu ersetzen.

Hier noch ein Beispiel für die Ergebnisse der Formatierung:

die Methode TScan::SetTitle vor der Kommentierung

BOOL TScan::SetTitle()
        {
        char  aTitle[MaxString];

#ifdef GermanVersion
        strcpy(aTitle,"Diffraktometrie:");
#else
        strcpy(aTitle,"Diffractometry:");
#endif
        if(bIsNewFile)
                strcat(aTitle,"");
                else
                strcat(aTitle,FileName);
        SetWindowText(hWndChild,aTitle);
        return TRUE;
        };

die Methode TScan::SetTitle nach der Formatierung incl. Kommentare

//! setzt Titel des ScanFensters
//! Rueckkehrcode immer True
BOOL TScan::SetTitle()
{
  char aTitle[ MaxString ];

  //! setzt aTitle
#ifdef GermanVersion
  strcpy( aTitle, "Diffraktometrie:" );
#else
strcpy( aTitle, "Diffractometry:" );
#endif
  //! haengt "" bei neuer Datei , sonst FileName an
  //! und schreibt ihn ins Fenster
  if ( bIsNewFile )
         strcat( aTitle, "" );
  else
         strcat( aTitle, FileName );
  SetWindowText( hWndChild, aTitle );
  return TRUE;
};

6.  Erweiterungen

Für die Umsetzung der Erweiterungen sind ca. 1900 LOC hinzugekommen und 230 Zeilen wurden entfernt. Geändert wurden ca. 200 LOC.
Bei der Benennung der neuen Klassen sowie der Methoden und Attribute wurde ver-sucht, dem bestehenden Stil zu folgen, um so die Lesbarkeit des Quelltextes erhalten zu können.
Für die Dialogelemente der neuen bzw. veränderten Dialogboxen wurden automatisch definierte ID’s in der Datei rc_def.h erstellt.
Weiterhin wurde beim Überarbeiten des Use-Case ‚Diffraktometrie/Reflektometrie’ bezüglich einer vollständigen Zweisprachigkeit in allen Meldungen, Hinweisen und Dialogboxen der größte Teil der Meldungen bzw. Hinweise im Kopfteil der Dateien m_arscan.cpp, m_scan.cpp und m_dlgdif.cpp als Variablen definiert.
Die nachfolgende Tabelle gibt zu jeder Erweiterung die Dateien an, in denen Veränderungen vorgenommen wurden. Dabei wurden zu den jeweils geänderten Klassen Angaben darüber gemacht, in welchem Umfang und an welcher Stelle (Methode) jeweils neue Quelltextzeilen hinzugekommen sind, alte entfernt bzw. vorhandene geändert wurden.

Legende:
+ hinzugefügt
- entfernt
+/- geändert

zuletzt geändert 11.11.2001 Jens Ullrich / Stephan Berndt