Inhalt

• History
• Einleitung
• Dokumentation außerhalb des Codes
• Code- Formalismen
• Allgemeine Benennungen
• Schlüsselwörter
• Dokumentation im Code
• Klassen
• Methoden
• Konstanten
• Variablen
• Beispielcode
• Literaturverzeichnis

History

Einleitung

Dieses Dokument soll festlegen, wie Code, der von den Projektmitgliedern des studentischen Projektes BALI implementiert wurde auszusehen hat. Ein einheitliches Aussehen hat nicht nur den Vorteil, das der Code nach außen hin sofort als Einheit erkannt wird, sondern vor allem auch daß bei von unterschiedlichen Gruppen modellierten Modulen, die Übersichtlichkeit und Verständlichkeit für alle Projektmitgliedes gewahrt bleibt. Sollen diese dann dieses Modul weiterentwickeln, bietet das "Äußere" des Codes bereits einige Hilfestellungen (durch Schriftkonventionen ist z.B. festgelegt wie Konstanten, Variablen und Prozedurnamen auszusehen haben. Allerdings dürfen die Konventionen nicht so weit gehen, daß dem Entwickler die Kreativität beim Entwicklungsprozeß genommen wird. Desweiteren wird festgelegt, wie außerhalb des Codes dokumentiert werden soll, damit sich die einzelnen Bestandteile auch nach außen hin oder als Referenz gut verwenden lassen.

Dokumentation außerhalb des Codes

Für die Dokumentation außerhalb des Codes bietet sich für Java- Source JAVADOC an, das bereits in Suns JDK enthalten ist und bei Angabe einer Source Datei alle signifikanten Informationen Vererbung, vorhandene Methoden alphabetisch geordnet, etc. als z.B. HTML- Dateien erstellt.

Die einzelnen Informationen zieht JAVADOC aus dem Sourcecode, in dessen Kommentaren man "Tags" einstreuen muß, um die einzelnen Angaben festzulegen.

Dies sind im einzelnen:

• Name des Moduls, Version und Datum :

/* @(#)gaga.java        1.00 97/05/02 */

• Version einer Klasse oder einer Methode

                /* @version     1.20, 02/05/96 */

• Autor einer Klasse oder einer Methode

                /* @author              Hans Wurst */

• Beschreibung und Parameter einer Methode

/**
* Returns the arc tangent of a, in range of -Pi/2 through Pi/2.
* @param a an assigned value
* @return the arc tangent of a.
*/
public static native double atan(double a);

Die Beschreibung, der einzelnen Klassen und Methoden findet direkt vor deren Definition statt:

/**
* Don't let anyone instantiate this class.
* 
* @version      1.00, 97/05/03 */
* @author               Hans Wurst */
*/
private gagahu() {}

Wir sollte uns diese Möglichkeit der Dokumentation unserer Programme warmhalten und einsetzen, da sie eine Menge Zeitersparnis bringt (die Zeit, die wir sonst zur externen Dokumentation bräuchten, können wir auch in die wesentliche Arbeit stecken!).

Code- Formalismen

Dieser Abschnitt soll festlegen, wie die einzelnen Komponenten von Java bzw. BALI Code in Listings angegeben werden.

Allgemeine Benennungen

Sowohl Klassen, Methoden, Konstanten, wie auch Variablen werden in englischer Sprache benannt.

Schlüsselwörter

Alle Schlüsselwörter werden klein geschrieben und nicht gesondert gekennzeichnet.

Dokumentation im Code

Damit die sich der Dokumentationsaufwand in Grenzen hält und sich Kapitel 4. Dokumentation außerhalb des Codes durchführen läßt, sollen alle JAVADOC- Tags benutzt werden.

Der gesamte Dokumentationstext wird in englischer Sprache abgefaßt. Der Dokumentationstext sollte so kurz wie möglich und so ausführlich wie nötig sein: Es tut wohl nicht Not jeden Bytedreher zu beschreiben, jedoch muß Anhand der Beschreibung klar werden was die Komponente im einzelnen macht. Aufrufende und aufzurufende Methoden und Klassen müssen nicht explizit angegeben werden, da diese Aufgabe sehr aufwendig ist und sich automatisieren läßt. Methodennamen vorangestellte Kürzel der Typen für Rückgabewerte und/ oder Parameter sind in typsicheren Sprachen wie Java oder BALI nicht notwendig, so daß man auch hierauf verzichten kann.

Klassen

Jeder Klassenname fängt grundsätzlich mit einem Großbuchstaben an. Vor jeder Klassendefinition erfolgt eine einleitende Beschreibung der Klasse, die Versionsnummer und der (die) Autorenname(n).

Bsp.:

/**
 * The NothingToDo class provides nothing, but a demonstration
 * @version     1.00, 03/05/97
 * @author              Hans Wurst
*/
public final class NothingToDo extends Number

...

Methoden

Jeder Methodenname wird klein geschrieben. Besteht der Methodenname jedoch aus mehreren Wörtern, so beginnen die nachfolgenden Worte mit einem Großbuchstaben. Vor jeder Methodendefinition erfolgt mindestens die Beschreibung der Methode. Die Bedeutung der einzelnen Parameter werden nach den @param- Tags beschrieben.

/**
     * Returns true if specified number is infinitely large in magnitude.
     * @param v the value to be tested
     */
static public boolean isInfinite(double v) {
...

Konstanten

Jeder Konstantenname wird komplett groß geschrieben. Vor jeder Methodendefinition erfolgt mindestens die Beschreibung der Konstante.

     /**
     * Positive infinity.
     */
    public static final double POSITIVE_INFINITY = 1.0 / 0.0;

Variablen

Jeder Variablenname wird klein geschrieben. Besteht er jedoch aus mehreren Wörtern, so beginnen die nachfolgenden Worte mit einem Großbuchstaben. Klassenvariablen bedürfen einer Beschreibung (wie bei ). Lokale Variablen bedürfen in der Regel ebenfalls einer Beschreibung, es sei den es sind "typische" Variablen, wie sie in der Klassen schon sehr oft vor kamen oder von allseits bekannter Bedeutung sind (das i der Zähler ist muß ja wohl keinem erklärt werden oder?).

Beispielcode

/*
 * Copyright (c) 1997 BALI/ University of Bremen All Rights Reserved.
 *
 * Permission to use, copy, modify, and distribute this software
 * and its documentation for NON-COMMERCIAL purposes and without
 * fee is hereby granted provided that this copyright notice
 * appears in all copies. Please refer to the file "copyright.html"
 * for further important copyright and licensing information.
 *
 * WE MAKE NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
 * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
 * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
 * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. WE SHALL NOT BE LIABLE FOR
 * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
 * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
 */

/*
* @(#)Gaga.java 1.34 96/05/02
 *
*/

package java.lang;

/**
 * The Gaga class provides nothing, but a demonstration of documentation
 * @version     1.00, 03/05/97
 * @author              Hans Wurst
*/

public final
class Gaga extends Number {
      /**
      * This is the Gaga constructor, which does nothing
      */
        public Gaga()
{
}

     /**
     * Positive infinity.
     */
     public static final double POSITIVE_INFINITY = 1.0 / 0.0;

     /**
     * Negative infinity.
     */
     public static final double NEGATIVE_INFINITY = -1.0 / 0.0;


     /**
     * Returns true if specified number is infinitely large in magnitude.
     * @param v the value to be tested
     */
    static public boolean isInfinite(double v) {
        return (v == POSITIVE_INFINITY) || (v == NEGATIVE_INFINITY);
    }
}

Literaturverzeichnis

[ArGo96]

Ken Arnold, James Gosling. Die Programmiersprache Java. Addison Wesley, Bonn, 1996

[CoHo96]

Gary Cornell, Cay S. Horstmann. Core JAVA. Sun Soft Press, Prentice Hall,
Mountainview (CA), 1996

[Sun96]

The Java Language Specification, Version 1.0 Beta, Sun Microsystems. Mountainview (CA), 30.10.1995