Your Federal Quarterly Tax Payments are due April 15th Get Help Now >>

Richtlinie für die Programmierung in Fortran by hcw25539

VIEWS: 10 PAGES: 9

									                                                                  PTB-RSE-F1.3
                                                                      2002-01-21




Titel       :   Informationstechnik - Richtlinien für die Softwareentwicklung -

                Richtlinie für die Programmierung in Fortran


Version     :   PTB-RSE-F1.3

Datum       :   2002-01-21

Verweise    :   Entwicklungsstandard für IT-Systeme des Bundes ( V-Modell )

Verfasser   :   N. Greif             Email: Norbert.Greif@ptb.de

                H. Schrepf           Email: Heike.Schrepf@ptb.de
                     Richtlinie für die Programmierung in Fortran




Inhalt:


1.        Einleitung                                                S. 3

2.        Anwendungsbereich                                         S. 3

3.        Begriffe                                                  S. 3

4.        Regeln                                                    S. 4

4.1.      Allgemeines                                               S. 4
4.2.      Fileorganisation                                          S. 4
4.3.      Kommentierung                                             S. 5
4.4.      Layout                                                    S. 6
4.5.      Namenskonventionen                                        S. 6
4.6.      Deklarationen                                             S. 7
4.7.      Kontrollfluss                                             S. 7
4.8.      Defensivprogrammierung, Fehlerbehandlung                  S. 8
4.9.      Sonstiges                                                 S. 8

Literatur                                                           S. 9
Weitere PTB-Richtlinien                                             S. 9




                                                                           2
1. Einleitung

Der steigende Anteil von Software in technischen Systemen erhöht in gleichem Maße die Bedeutung
der Softwarequalität. Einen Beitrag zur Gewährleistung einer hohen Softwarequalität leisten firmen-
bzw. projektspezifische Richtlinien für die Softwareentwicklung. Sie dienen insbesondere als
Arbeitsanleitung, Kommunikationsbasis und Vertragsgrundlage.

Die vorliegende Programmierrichtlinie enthält Regeln für das Codieren und Kommentieren in der
Programmiersprache Fortran.


2. Anwendungsbereich

Das Ziel der Richtlinie besteht darin, bei Softwareentwicklungen in der PTB oder bei der Vergabe von
Entwicklungsaufträgen die Qualität der Programme dadurch zu verbessern, dass bekannte fehler-
anfällige Sprachkonstrukte vermieden und anerkannte qualitätssichernde Elemente empfohlenen
werden. Insbesondere sollen Eigenschaften wie Zuverlässigkeit, Robustheit, Wartbarkeit und
Testbarkeit der Software gesichert werden. Die Richtlinie
• weist deshalb auf bestimmte, als fehleranfällig bekannte Sprachkonstrukte hin und
• gibt Empfehlungen für die Code-Kommentierung.

Es ist kein vorrangiges Ziel der Richtlinie, durch ihre Anwendung die Programme portabel zu
gestalten. Portabilität ist in vielen Fällen nicht erforderlich, und die sich unmittelbar aus ihr ergebende
Forderung nach Normkonformität widerspricht in einigen Fällen sogar den hier formulierten Regeln.
Unabhängig davon sollte sich kein Programmierer ohne zwingenden Grund von den existierenden
Sprachstandards entfernen und proprietäre Sprachkonstrukte einsetzen.

Es ist ebenfalls kein Ziel der Richtlinie, durch Weitergabe besonderer Programmiertipps und -tricks
die zu entwickelnde Software effizient zu machen. Solche Art von Effizienz auf der einen Seite und
Zuverlässigkeit und Wartbarkeit auf der anderen Seite führen in der Regel zu einander
widersprechenden Forderungen an den Code. Als Konsequenz ist die Anwendung der Richtlinie also
zumindest dann nicht sinnvoll, wenn die zu entwickelnde Software unter allen Umständen
vorgegebene enge Effizienzkriterien erfüllen muss, z.B. wenn harte Echtzeitforderungen bestehen. In
diesen Fällen können bestimmte Regeln nicht angewendet werden und Qualitätsnachweise müssen,
wenn sie erforderlich sind, gesondert geführt werden. Regeln, die sich z.B. auf die Code-
Kommentierung oder die Namenskonventionen beziehen, stehen der Effizienz jedoch nicht im Wege.

Die Anwendung der Richtlinie wird empfohlen bei Softwareentwicklungen in der PTB, wenn
• deren Einsatz im gesetzlich geregelten oder Dienstleistungsbereich erfolgt oder vorgesehen ist
   (z.B. Kalibrierungen, Bauartzulassungen),
• die fertige Software veräußert werden soll,
• an Entwicklung, Wartung und Einsatz Personen unterschiedlicher Labore oder Projekte beteiligt
   sind.

Bei der Vergabe von Softwareentwicklungsaufträgen an Fremdfirmen kann die Richtlinie dann
vertragswirksam angewendet werden, wenn der Auftragnehmer keine adäquate hauseigene Richtlinie
zur Verfügung hat.

Darüber hinaus wird die Anwendung der Richtlinie bei jeder weiteren Softwareentwicklung empfohlen,
• wenn deren Umfang 500 Quelltextzeilen (ohne Kommentar) überschreitet oder
• wenn deren vorgesehene Anwendungsdauer mindestens 1 Jahr beträgt.


3. Begriffe

Symbol              Durch den Programmierer eingeführtes, eindeutig identifizierbares, neues
                    Programmwort (Variable, benannte Konstante, Funktion, Prozedur, COMMON-Block,
                    Typ, Parameter, Label, ...). Der Name muss nicht eindeutig sein und kann u.U.
                    auch im Code fehlen.
Modul               Sammlung von Deklarationen und Definitionen, die separat kompilierbar ist
                    (PROGRAM, MODULE).
Routine             Funktion oder Prozedur.

                                                                                                              3
4. Regeln

Dieser Abschnitt enthält die Regeln für das Codieren und Kommentieren. Einzelne Regeln sind um
kurze Erläuterungen oder Empfehlungen ergänzt. Diese Texte sind nicht Bestandteil der jeweiligen
Regel.

Der Grad der Verbindlichkeit ist für alle Regeln gleich und hängt nicht davon ab, ob die Regel mittels
„muss“, „sollte“ oder „ist ... zu“ gebildet wird.


4.1. Allgemeines

F0    Wenn eine Regel aus einem besonderen Grund nicht eingehalten werden kann, ist dies kurz im
      Code zu dokumentieren und zu begründen.
      Es ist möglich, dass fachliche Gründe die Einhaltung einer Regel unmöglich machen.


F1    Falls ein entsprechender Compiler vorhanden ist, sind die Möglichkeiten zu nutzen, die
      Fortran 90 für die Datenkapselung bietet. Ansonsten ist Fortran 77 zu verwenden.
      Fortran 90/95 ist definiert in der ISO/IEC 1539:1991/1997. Fortran 77, definiert in ANSI X3.9:1978, ist formal nur noch in
      den USA als Standard gültig. Der Standard ISO/IEC 1539:1991 ist in der Bibliothek Charlottenburg verfügbar.

      Fortran 90 ist eine echte Obermenge von Fortran 77. Die wichtigsten Erweiterungen sind: Definition von MODULEs mit
      expliziter Schnittstelle, Überladen von Funktionen und Operatoren, Definition von Strukturen und Pointern, CASE-
      Konstrukt, Array-Arithmetik, benannte Schleifen, optionale und Keyword-Parameter.

      Die Forderung nach Normkonformität bezieht sich auf Sprachkonstrukte. Zu Fortran 77 nichtkonforme Sprachkonstrukte
      sind z.B. die Deklaration von RECORD, das VIRTUAL-Statement, die Verwendung von Debug-Zeilen (mit D),
      Variablenattribute wie AUTOMATIC oder VOLATILE, usw. Erweiterungen in Form von Funktionssammlungen
      (Bibliotheken) oder zusätzlichen intrinsic-Funktionen, bzw. alles, was nachimplementierbar wäre, ist zulässig.


4.2. Fileorganisation

F2    Falls das System portiert oder transportiert werden muss, sind Filenamen entsprechend den
      ISO-Konventionen zu wählen.
      In der ISO 9660 sind folgende Regeln für File- und Verzeichnisnamen festgelegt: Für die Namen sind Buchstaben,
      Ziffern und Underscore ‘_’ zugelassen. Verzeichnisnamen sind max. 8 Zeichen lang und haben keine
      Namenserweiterung. Filenamen sind max. 8 Zeichen lang und haben eine Namenserweiterung mit max. 3 Zeichen.
      Name und Namenserweiterung werden durch ein Dot ‘.’ getrennt.


F3    Falls das System portiert werden muss, sind nichtnormkonforme Zugriffe zu Hardware und
      Betriebssystem, die sich nicht vermeiden lassen, in einem separaten Modul
      zusammenzufassen.

F4    Die Include-Anweisungen dürfen keine absoluten Pfade enthalten.
      In der Regel kann jedem Compiler über Umgebungsvariablen die Lage der Include-Verzeichnisse mitgeteilt werden.
      Dann ist keinerlei Pfadangabe nötig. Falls das nicht möglich ist, müssen die zu inkludierenden Files im aktuellen
      Verzeichnis oder seinen Unterverzeichnissen deponiert werden.


4.3. Kommentierung

F5    Jedes File ist mit einem Kommentar einzuleiten. Dieser sollte Name und Zweck des Files,
      Autor, Erstellungsdatum oder Version sowie eine Änderungsliste enthalten.
      Der Kommentar kann auch verschiedene andere Dinge auflisten, z.B. die im File enthaltenen Deklarationen, evtl.
      bekannte Restriktionen, noch fehlende Teile, eine Liste der nicht vermeidbaren Compilerwarnungen u.a.




                                                                                                                              4
      Beispiel:
          C ---------------------------------------------------------------
          C MyString.for
          C Funktionen fuer die komfortable Stringbehandlung
          C (Case-insens. Vergleichen, kopieren, swappen und Substr. bilden).
          C HS 10. 7. 97
          C
          C Aenderungen:
          C 21. 7.     StringCopy: Fall Anzahl n .lt. 0 wird jetzt abgefangen.
          C ---------------------------------------------------------------


F6    Jede Routinendefinition ist mit einem Kommentar einzuleiten. Dieser sollte Name und Zweck
      der Routine, Bedeutung der Parameter und des Rückkehrwertes, evtl. Definitionsbereich der
      Eingabeparameter, verwendete COMMON-Blöcke oder -Variablen, Seiteneffekte oder sonstige
      Besonderheiten enthalten.
      Der Definitionsbereich der Eingabeparameter ist nur dann anzugeben, wenn er gegenüber dem Datentyp eingeschränkt
      ist.

      Beispiel:
          C --------------------------------------------------------------
          C CHARACTER*20 FUNCTION GetPartialString(InString, StartPos, Number)
          C
          C Liefert einen Teilstring eines eingegebenen Strings zurueck.
          C
          C Inputs:
          C     InString: Eingabestring beliebiger Laenge
          C     StartPos: Nr. des ersten Zeichens, das uebernommen werden soll.
          C     Nummer:   Anzahl von Zeichen, die uebernommen werden sollen.
          C Outputs:
          C     Rueckkehrwert: Teilstring mit maximal 20 Zeichen.
          C COMMONs: -
          C Die Funktion ueberprueft selbst StartPos und Number. InString wird
          C nicht ueberprueft.
          C --------------------------------------------------------------


F7    Jeder COMMON-Block muss kommentiert werden. Der Kommentar muss die Funktion der in ihm
      enthaltenen Variablen erläutern. Falls der Definitionsbereich der Variablen im Programm kleiner
      ist als der durch ihren Datentyp zugelassene Bereich, ist das im Kommentar zu vermerken.
      Statt am Ort der Definition oder Deklaration können die COMMON-Blöcke auch im Filekommentar (siehe F5) erläutert
      werden.


F8    Die Direktiven $ELSE und $ENDIF sind mit einem Kommentar zu versehen, der beschreibt, zu
      welchem $IF sie gehören.

F9    Jede Kommandozeilenoption, die als Direktive im Quelltext steht, muss kommentiert werden.

F10   Überflüssige, im Laufe der Entwicklung entstandene und in Kommentar umgewandelte
      Quelltextabschnitte müssen in der endgültigen Fassung entfernt werden.

F11   Zwischen Fortsetzungszeilen sind keine Kommentarzeilen erlaubt.




                                                                                                                         5
4.4. Layout

F12   Routinen sollten nicht länger als eine Bildschirmseite (etwa 25 Zeilen) sein.
      Die genaue Anzahl von Zeilen ist nicht wichtig. Der hinter dieser Regel stehende Gedanke ist, dass a) Blättern auf dem
      Bildschirm das schnelle, intuitive Erfassen einer Funktion behindert und b) lange Funktionen nicht testbar sind. Je
      einfacher eine Funktion strukturiert ist (einfache Sequenz), desto länger kann sie sein, ohne ihre Testbarkeit zu
      verlieren.


F13   Der Code ist durch gezielte Einrückungen und optische, blockweise Strukturierung lesbar zu
      gestalten.

F14   Falls lange Zeilen geteilt werden müssen, ist der Zeilenumbruch vor, nicht nach einem Operator
      einzufügen.
      Der Operator der obersten Klammerungsebene sollte die Fortsetzungszeile beginnen.

      Beispiel:    IF   ((      thisIsALongLine .AND. thisIsADemonstration                 )
                  * .OR. (      thisLineContainsText))    THEN ...


F15   Keine Anweisung sollte über mehr als zwei Zeilen gehen.


F16   DATA-Anweisungen müssen vor den ausführbaren Anweisungen einer Routine stehen.
      DATA-Anweisungen dürfen zwar syntaktisch überall im Code erscheinen, werden aber auf jeden Fall vor der ersten
      ausführbaren Anweisung ausgeführt.


F17   Für jede COMMON-Definition ist eine separate Zeile zu verwenden.


4.5. Namenskonventionen

F18   Vor der Implementierung sind Namenskonventionen aufzustellen, die konsequent eingehalten
      werden müssen.
      Empfehlenswert ist, diese Namenskonventionen in einem der Filekommentare (siehe F5) niederzulegen.


F19   Symbolnamen sollten selbsterklärend sein. Sie sind geeignet zu untergliedern, wenn sie aus
      mehreren Wörtern bestehen.
      Beispiele: peters_first_car, PetersFirstCar.


F20   Die Fortran-Keywords und die Namen der Intrinsic-Funktionen sind als nutzereigene
      Symbolnamen nicht zulässig.
      Ist ausdrücklich gewünscht, die Funktionalität einer Intrinsic-Funktion durch Verwendung ihres Namens zu ersetzen,
      dann muss jeder Verwendung der neuen, nutzerdefinierten Funktion ein entsprechender Kommentar beigefügt werden.


F21   Namen von globalen Symbolen sollten mindestens 6 Zeichen lang sein.
      Der ANSI-Standard für Fortran 77 sieht nur 6 signifikante Zeichen für global sichtbare Symbole vor, die meisten
      Compiler erlauben aber heute mindestens 31 signifikante Zeichen. Fachlich gebräuchliche oder aus der Mathematik
      stammende Namen wie Pi sind zulässig.


F22   Falls Konstanten wie YES und NO o.ä. definiert werden, ist der semantisch negativ belegten
      Konstanten (NO) der Wert 0 oder .FALSE. zuzuweisen.

F23   COMMON-Blöcke und Variablen dürfen nicht denselben Namen haben.




                                                                                                                           6
F24   Falls ein F90/95-Compiler verwendet wird, sind Kontrollflusskonstrukte (DO-Schleifen), die über
      mehr als 10 Zeilen reichen, oder die dreifach oder tiefer geschachtelt sind, zu benennen.


4.6. Deklarationen

F25   Jedes Symbol sollte den kleinstmöglichen Gültigkeitsbereich haben.
      Variablen, die nur in einer Routine verwendet werden, sind lokal zu dieser zu definieren. Zusammengehörige Routinen,
      Typen und Variablen sind in F90/95 zu Modulen mit expliziter Schnittstelle zusammenzufassen. (Benannte) Konstanten
      dürfen global definiert werden, auch wenn sie nur lokal verwendet werden.


F26   Alle Typangaben sollten die Größe beinhalten.
      Statt INTEGER i ist INTEGER*4 i zu schreiben, auch wenn dies nicht dem ANSI Fortran 77-Standard entspricht.


F27   Zahlenwerte sollten nicht direkt in den Code geschrieben werden. Sie sind vorher zu definieren.
      Für die vorherige Vereinbarung von Konstanten gibt es einige Ausnahmen:
      • Die Zahlen -1, 0 und 1, wenn sie im Sinne boolescher Werte verwendet werden,
      • einzelne Zeichen und
      • der zweite Operand von Bit-Operationen (Shifts, Maskierungen).


F28   Das implizite Ändern der Dimension einer Feldvariablen bei der Parameterübergabe ist nicht
      erlaubt.

F29   Jedes Modul muss die Anweisung IMPLICIT NONE enthalten.

F30   Alle Deklarationen eines COMMON-Blocks müssen gleich sein.

F31   Die Verwendung des cH-Deskriptors ist zu vermeiden.
      cH wird im nächsten Fortran-Standard wahrscheinlich nicht mehr enthalten sein (sogenanntes ‘obsolescent feature’ von
      Fortran 90).


4.7. Kontrollfluss

F32   Sprünge mit GOTO sind nur aus einem Schleifenkörper heraus an das Schleifenende erlaubt.
      Jede GOTO-Anweisung ist zu kommentieren. Das Sprungziel muss eine CONTINUE-Anweisung
      sein.

F33   In F90/95 ist GOTO generell nicht erlaubt.
      Hier sind für die Sprünge an das Schleifenende EXIT oder CYCLE zu verwenden.


F34   Statt DO mit Label ist END DO zu verwenden.

F35   Label sind nur zulässig vor CONTINUE und FORMAT Anweisungen.

F36   Jedes CASE-Konstrukt (F90/95) muss mit einem DEFAULT-Zweig beendet werden.

F37   ENTRY darf nicht verwendet werden.

F38   Schleifenvariablen müssen einen ordinalen Typ haben.
      Gebrochene Schleifenvariablen sind im nächsten Fortran-Standard wahrscheinlich nicht mehr enthalten.




                                                                                                                         7
F39   Arithmetisches IF sollte vermieden werden.
      Das arithmetische IF ist im nächsten Fortran-Standard wahrscheinlich nicht mehr enthalten.


F40   Alternativ-Returns der Form RETURN <NN> sind nicht erlaubt.
      Alternativ-Returns sind im nächsten Fortran-Standard wahrscheinlich nicht mehr enthalten.


F41   Die Anweisungen ASSIGN, PAUSE, PRINT, TYPE, ACCEPT sollten vermieden werden.
      Diese Keywords sind im nächsten Fortran-Standard wahrscheinlich nicht mehr enthalten.


F42   In einer Anweisung definierte Funktionen (statement functions) sind nicht erlaubt.
      Statement functions sind im nächsten Fortran-Standard wahrscheinlich nicht mehr enthalten.


F43   Falls das Programm auf ein bestimmtes Ereignis wartet (Beendigung einer Berechnung,
      Interrupt, Nutzereingabe, ...) muss dies für den Benutzer erkennbar sein.


4.8. Defensivprogrammierung, Fehlerbehandlung

F44   Vor der Implementierung ist ein System der Fehlerbehandlung festzulegen, das konsequent
      eingehalten wird.
      Günstig ist es, das Fehlerbehandlungsprinzip in einem der Filekommentare (siehe F5) niederzulegen.


F45   Jede Möglichkeit zum Testen von Rückkehrwerten oder Statusvariablen auf Erfolg oder
      Misserfolg muss genutzt werden.
      Viele Routinen, z.B. ALLOCATE oder OPEN, liefern Statusparameter zurück, die geprüft werden sollten.


F46   Jede Routine muss zu Beginn ihre Ausgabevariablen zurücksetzen.
      Ausgabevariablen einer Routine können neben Rückkehrwerten und Ausgabeparametern auch COMMON-Variablen sein.
      Kombinierte Ein-/Ausgabewerte sind nicht gemeint.


F47   Jede Division muss durch einen vorherigen Null-Test des Nenners geschützt werden.
      Statt result = a/b ist zu schreiben IF (b .NE. 0) THEN result = a/b ELSE .. ENDIF


F48   Jedes Wurzelziehen muss durch einen vorherigen Test des Radikanden geschützt werden.

F49   Jedes Logarithmieren muss durch einen vorherigen Test des Arguments geschützt werden.


4.9. Sonstiges

F50   Zwei gebrochene Zahlen sowie eine gebrochene und eine ganze Zahl dürfen nur über eine
      Toleranz (eps) auf Gleichheit oder Ungleichheit überprüft werden.




                                                                                                                 8
Literatur

Sprachstandards
ISO/IEC 1539:1991, Information Technology -- Programming Languages -- Fortran
ISO/IEC 1539-1:1997, Information Technology -- Programming Languages -- Fortran -
      Part 1: Base Language
ISO/IEC 1539-2:1994, Information Technology -- Programming Languages -- Fortran -
      Part 2: Varying length character string
ISO/IEC 1539-3:1999, Information Technology -- Programming Languages -- Fortran -
      Part 3: Conditional compilation
ISO/IEC TR 15581:1998 Information Technology – Programming Languages – Enhanced data type
      facilities
ISO/IEC TR 15580:1998 Information Technology – Programming Languages – Floating-point
      exception handling

ANSI X3.198:1992 (R 1997) Programming Language – Fortran – Extended

IEEE 1003.9-1992 IEEE Standard for Information Technology – POSIX A® - Fortran 77 Language
      Interfaces – Part 1: Binding for System Application Program Interface (API)

Filenamenskonventionen
ISO 9660:1988, Information processing -
      Volume and file structure of CD-ROM for information interchange.

Programmierregeln und Namenskonventionen (Beispiele)
Fortran Programming Conventions for ATLAS offline Software
      http://atlasinfo.cern.ch/Atlas/GROUPS/SOFTWARE/DOCUMENTS/CODE_CONV/coding_conventions/co
      ding_conventions.html
J. Bunn Coding Conventions in Floppy, CERN Computing and Networks Div.
      http://www.netlib.org/floppy/contents.html#link4
P. Andrews et.al. European Standards For Writing and Documenting Exchangeable Fortran 90 Code,
      UK Meteorological Organization
      http://www.meto.gov.uk/sec5/NWP/NWP_F90Standards.html
A. C. Saulys STAR Coding Style Manual, STAR Software Library
      http://www.rhic.bnl.gov/STAR/html/ssd_l/style/node2.html



Weitere PTB-Richtlinien

Richtlinie für die Programmierung in C.
Richtlinie für die Programmierung in C++.
Richtlinie für die Programmierung in Pascal.
Richtlinie für die Programmierung in Visual Basic.
Richtlinie für die Softwaredokumentation.




                                                                                             9

								
To top