Checkliste Codeentwicklung

Bevor Sourcecode als stabil anerkannt werden kann, müssen folgende formalen Inspektionen durchgeführt werden:

• HTML Beschreibung des Programms, Codes vorhanden?
• Ist in HTML Beschreibung das Copyright eingetragen?
• Javadoc vorhanden und verständlich?
• JUnit Testklassen vorhanden?
• Decken die JUnit Testklassen die notwendigsten Eigenschaften ab?
• Copyright in den Sourcecodes vorhanden?
• Autor Tag definiert?
• Installationsscripts (ANT) vorhanden und funktionsfähig?
• Installationsscripts dokumentiert?
• Konfigurationsdateien vernünftig aufgebaut? (RootPath und relative Pfade usw.)
• Code verständlich geschrieben und wartbar?

VirtL Coding Styleguide

Folgende Style-Regeln wurden vereinbart:

Verwendeter Styleguide

Der Styleguide für die Entwicklung wurde von Standard Entwicklungsstyleguides (SUN) übernommen.
Die Klammerung und Einrückung bei VirtL sieht wie folgt aus:

class Demo{
    protected boolean aMethod(Element currentElement) {
        try{	
            for(int i = 0; i < value; i++){
                computesomething;
                if(something = anything){
                    green = red;	
                    return;
                }
            }
        }catch (Exception e){
            CatchSomething;
        }	
        return something;
    }
}

Sourcedokumentation

Da bei VirtL viel Wert auf Dokumentation gelegt wird, lässt es sich nicht vermeiden auch die Sourcen ausführlich und durchgängig zu dokumentieren.

Copyrightangabe in den Klassen

Jede Klasse beginnt mit dem LGPL Copyright, das folgenden Inhalt aufweist:

/** 
 * Copyright (c) 2006, Name des Autors
 * 
 * This file is part of VirtL.
 * 
 * VirtL is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * VirtL is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

Klassendokumentation

Die Klasse wird mit einem Changelog und der eigentlichen Beschreibung der Klasse beschrieben. Bei der Beschreibung der Klasse wird mit einem kurzen einleitenden Satz begonnen. In der zweiten Zeile wird eine lange Beschreibung der Klasse eingetragen. Javadoc verwendet die Kurzbeschreibung für die Übersichtsdarstellung und die lange Beschreibung in der detaillierten Beschreibung der Klasse.

/**
 * Changelog
 * 2006.02.28 Roland Baldenhofer Created.
 * 2006.03.14 Roland Baldenhofer Fixed the problem... .
 */


/**
 * Uses the navigation.xml to build the navigation for the specific HTML pages.

 * For each HTML page it will create a special navigation tree. This navigation tree can be inserted in
 * the given files...
 * @author Roland Baldenhofer
 *
 */
public abstract class AbstractNavigationCreator {...

Methodendokumentation

Es werden alle public, protected und private Methoden und Klassen durchgängig dokumentiert, wobei mit einem kurzen einleitenden Satz begonnen wird an den eine längere Beschreibung angeknüpft wird. Im Javadoc wird der kurze einleitende Satz in der Kurzbeschreibung angegeben während die lange Beschreibung bei der eigentlichen Methodenbeschreibung aufgelistet wird.

Alle Übergabeparameter (in und return) werden beschrieben. Falls eine Methode Exceptions wirft, wird dies mit @throws beschrieben. Ist die Methode von einer Superklasse abgeleitet, wird mit dem @see tag auf die abgeleitete Methode verwiesen.
Beispiel:

/**
 * Creates the navigation by traversing the navigation.xml document.

 * Here we write what the method implements.
 * @param aParameter Description of the parameter.
 * @return true If everything is cool.

 *         false If there is something very bad. 
 * @throws NullPointerException If aParameter is null.
 * @throws IndexOutOfBoundsException If something is bad.
 */

Variablendokumentation

Es werden alle public, protected und private Variablen beschrieben. Meistens reicht bei der Beschreibung der Variablen ein einzelner Satz aus.
Beispiel;

/**
 * Stores all navigations of rhe presentation. 
 */
protected AbstractNavigation _leftNavigation;