1. Eigene Java Code Convention Dokumentationskonzept Soweit nichts Abweichendes angegeben, sind die Implementierer dazu gehalten, sich an die Regeln für guten Code aus den allgemeinen SUN Konventionen zu halten Sourcecodestruktur - Sourcecodedateien: Jede public - Klasse wird in eine eigene Datei geschrieben package.html... HTML Datei, die genauere Informationen über ein Paket enthält und in der Verzeichnisstruktur in diesem Paket liegt Jede Datei enthält nur genau eine öffentliche Klasse. Wenn eine private Klasse mit einer öffentlichen zusammenhängt, dann kann diese in dieselbe Datei geschrieben werden, die öffentlich Klasse steht aber dabei immer am Dateianfang! - Folgende Anordnung der Elemente ist einzuhalten Quellcode beginnt mit einem Kommentar im C-Stil (/ \n \n /), der folgendes enthält: / Klassenname detaillierte Versionsinformation Erstellungsdatum/letzte Änderung Copyright / danach folgen package- und import- Anweisungen: package de.lv.<subpackage> import ; anschließend beginnt die eigentliche Klassen- / Interface Deklaration, welche im üblichen javadoc Format kommentiert werden soll: / / der Klassenname beginnt immer mit einem Großbuchstaben und sollte selbsterklärend sein! Auf Abkürzungen ist zu verzichten, außer wenn diese mehr genutzt werden, als das ausgeschriebene Wort (wie z.b. URL oder XML) die Reihenfolge der Variablen und Methoden der Klasse orientiert sich an folgendem Schema statische Klassenvariablen: public, protected, package, private Objektattribute: public, protected, package, private Konstruktoren Methoden, welche nach Fachlichkeit sortiert werden und nicht nach Sichtbarkeit Die Klammern werden grundsätzlich immer in eine neue Zeile gesetzt, wie folgendes Beispiel zeigt: Seite 1 von 5
for (.) { } Namenskonventionen - Package - Deklarationen werden komplett klein geschrieben - Klassennamen Sind Substantive, welche mit Groß- und Kleinbuchstaben geschrieben werden, wobei jeder erste Buchstabe eines internen Wortes ein Grossbuchstabe ist Selbsterklärende und einfache Namen verwenden Ganze Worte nehmen Akronyme und Abkürzungen vermeiden - Interfaces Beginnen mit einem Grossbuchstaben, wie Klassennamen - Methoden Verben, welche mit Groß- und Kleinbuchstaben geschrieben werden, wobei jeder erste Buchstabe eines internen Wortes ein Grossbuchstabe ist - Variablen Fangen nicht mit _ oder $ an Werden mit Groß- und Kleinbuchstaben geschrieben, wobei jeder erste Buchstabe eines internen Wortes ein Kleinbuchstabe ist Sind kurz und mnemonisch, also selbsterklärend - Konstanten Namen von Variablen deklarieren Klassenkonstanten ANSI Konstanten werden immer mit Großbuchstaben geschrieben, die Trennung der einzelnen internen Worte erfolgt hierbei mit _ Statements - Bei zusammenhängenden Blöcken (wie if, for, while, try - Blöcken) immer Klammern setzen, auch wenn der Block nur über eine Zeile geht 2. Qualitätsstandards Von besonderer Wichtigkeit für das Projekt ist die Wartbarkeit, da das Programm in späteren Lebenszyklen um weitere Funktionalitäten ergänzt werden soll. Dies geschieht nicht nur durch einen Administrator, sondern kann durch die Situation am Lehrstuhl von wechselnden Personen durchgeführt werden. Daher ist auch der Aufwand zur Einarbeitung in das Projekt möglichst einfach zu halten. Die Lesbarkeit, Verständlichkeit und Wartbarkeit des Codes sind daher auf hohem Niveau zu gewährleisten. Die Erfüllung dieser Kriterien verringert das Einsatzrisiko der Software, minimiert den Schulungsaufwand neuer Projektmitarbeiter und hält die Kosten der Wartung und Weiterentwicklung so gering wie möglich. Die Codequalität hat also auch auf die Wirtschaftlichkeit von dem Softwareprodukt einen hohen Einfluss. Daher ist es notwendig, die von den Programmierern erzielte Qualität von Zeit zu Zeit durch einen Code - Review zu überprüfen. Die Software sollte außerdem möglichst absturzsicher sein und im Falle eines Absturzes ein detailliertes Fehlerprotokoll zur Verfügung stellen, damit die Fehlersuche schnell vonstatten gehen Seite 2 von 5
kann. Da das Projekt in einer Web-Umgebung läuft, sollten die Antwortzeiten möglichst gering sein, weil die Daten noch an den jeweiligen Client gesendet werden müssen, was je nach Verbindungsgeschwindigkeit länger dauern kann. Genauere Einzelheiten dazu werden im Lasten- und Pflichtenheft geregelt. Seite 3 von 5
3. Vorgehensweisen und Verantwortlichkeiten für bestimmte Teile der Dokumentation Vorgehensweise Im Rahmen des Projekts entsteht eine umfangreiche Dokumentation. Für ein gut dokumentiertes Software-Produkt sind mindestens vier Arten der Dokumentation nötig. Hierbei lässt sich unterscheiden in: - Inline Source Dokumentation, worunter man das Einfügen von Kommentaren direkt in den Programmcode versteht. Dies geschieht nach den vorher festgelegten Code Konventionen. - Schnittstellenbeschreibung, dies sind Dokumente, welche Anzahl, Typen und erlaubte Reihenfolge von Daten angeben, die zwischen Softwaremodulen ausgetauscht werden. Zusätzlich werden hier die Randbedingungen festgelegt. - Technische Dokumentation, darunter ist ein Dokument bzw. eine Dokumentensammlung zu verstehen, in der sich alles wieder finden lassen sollte, was mit der Implementierung zu tun hat und nicht in der Inline Source Dokumentation oder der Schnittstellenbeschreibung zu finden ist. Diese Dokumentation sollte insbesondere die Funktionsprinzipien der Software von einem höher stehenden Standpunkt als die Inline Source Dokumentation beschreiben. - Design Dokumentation; hier erfolgt die Technifizierung der fachlichen Anforderungen, d.h. der Analyseergebnisse. Hier muss ein Weg zwischen dem Kundenwunsch und der technischen Machbarkeit gefunden werden, was oft zu Einschränkungen in der Funktionalität führt. Hierzu gehören auch alle anderen Formen von Dokumentation, welche die Teile in ihrem Zusammenspiel abbilden, wie zum Beispiel UML - Diagramme. Zu der Dokumentation gehört aber auch das Benutzerhandbuch, welches die Visitenkarte des Produktes darstellt und den Schlüssel für die Benutzung des Softwareproduktes für den Anwender ist. Das Benutzerhandbuch beinhaltet die Produktbestandteile, Arbeitsobjekte, Produktfunktionen, Produktstruktur und die Arbeitsabläufe. Die Abfolge der Dokumente für ein Software-Produkt ist folgende: Entwicklung des Designdokumentes Erstellung des Technischen Dokumentes samt der Schnittstellenbeschreibung Inline Source Dokumentation Verantwortlichkeiten Verantwortlicher für Test: Er muss die Kontrolle des Quellcodes auf die Einhaltung der festgelegten Code Convention und auf valide Dokumentation der Schnittstellen durchführen, damit ohne größeren Aufwand automatisierte Tests für die einzelnen Funktionalitäten durchgeführt werden können. Durch falsche oder ungenügende Dokumentation der Schnittstellen des Programms kann es zu Problemen im Umgang mit diesem kommen, daher ist der Verantwortliche für Tests auch dafür zuständig, dass eine ausreichende Beschreibung dieser implementiert wird. Verantwortlicher für Dokumentation: Er muss die Kontrolle des Quellcodes auf die Einhaltung der festgelegten Code Convention durchführen. Er ist außerdem zuständig für das Sammeln der Informationen aus dem Quelltext (javadoc/inline comments) und von den Programmieren, welche nötig sind, um eine begleitende Dokumentationen anzufertigen. Darunter zählt z.b. das Handbuch. Er ist also verantwortlich für die Kontrolle und das Auswerten aller Daten die unter dem Punkt der Vorgehensweise erwähnt wurden. Seite 4 von 5
Verantwortlicher für Implementierung: Muss die vorher festgelegten Code Convention während des Implementierens einhalten. Dabei sollte schon beim Implementieren darauf geachtet werden, dass der Quellcode sofort und mit den vorher definierten Richtlinien für die Kommentierung dokumentiert wird. Er ist aber auch zuständig für das Sammeln der Informationen, um daraus im späteren Verlauf der Software-Produktion ein Handbuch u.ä. erstellen zu können. Seite 5 von 5