2019.06 2020.06

Festlegungen für die Code Entwicklung

Vorbemerkungen

Von den MyCoRe-Entwicklern wird eine Entwicklungsumgebung wie Eclipse IDE oder IntelliJ IDEA zur Arbeit am MyCoRe-Projekt empfohlen.

Einheitliche Format-Konventionen sind die Voraussetzung dafür, dass Änderungen an den Dateien im Github-Repository nachvollziehbar bleiben. Deshalb sollten neue und geänderte Dateien vor einem Commit automatisch mit folgenden Einstellungen formatiert werden:

Encoding

Allgemeines

Grundsätzlich geht MyCoRe davon aus, dass alle Dateien, die nicht sprachabhängig sind, mit UTF-8 kodiert sind. Dies betrifft vor allem die Dateitypen:

Java-Code: *.java
XML-/XED-/XSD-/XSL-Dateien: *.xml, *.xed, *.xsd, *.xsl
HTML-Dateien: *.html, *.xhtml

Konfiguration unter Eclipse

Die Einstellung erfolgt in Eclipse global für alle Dateien unter:

Anwendungs-Menü:
Window → Preferences → General → Workspace → Text file encoding → Other: UTF-8

Für einzelne Dateien kann die Eigenschaft auch in den Properties gesetzt werden:

Context-Menü (rechte Maustaste / Alt+Enter):
Properties → Resource → Text file encoding → Other: UTF-8

Formatierung der Dateien

Um bei der Arbeit mit Git nur funktionale Änderungen zu commiten und diese nicht mit Änderungen an der Formatierung zu vermischen, wird der gesamte Code einheitlich nach folgenden Regeln erstellt:

Java Importorder

Die Import-Reihenfolge für Java-Packages lautet:

java
javax
org
com

Konfiguration unter Eclipse

Die Einstellung erfolgt unter:

Anwendungs-Menü:
Window → Preferences → Java → Code Style → Organize Imports

Dort lässt sich die oben beschriebene Reihenfolge einstellen.
Alternativ kann diese ImportOrder-Konfiguration heruntergeladen und importiert werden.

Java-Code Formatierung

Allgemeines

Für die Formatierung von Java-Dateien gelten folgende Regeln:

Formatierung gemäß den Java-Konventionen
Tabulatoren werden durch Leerzeichen ersetzt
Einrückung mit vier Zeichen
Zeilenumbruch und maximale Zeilenlänge 120
Kommenare nicht umformatieren

Konfiguration unter Eclipse

Die Einstellung erfolgt unter:

Anwendungs-Menü:
Window → Preferences → Java → Code Style → Formatter

Dort wählt man das Profile Java Conventions [built-in] als Vorlage und nimmt folgende Anpassungen vor:

Indentation:
- Tab Policy: Spaces only
- Indentation size: 4 (default)
- Tab size: 4
- Statements within 'switch' body: [on]
New Lines:
- At end of file: [on]
Line wrapping:
- Maximum line width: 120 (default)
- Default indentation for wrapped lines: 1
- Default indentation for array initializers: 1
- Never join already wrapped lines: [on]
Line wrapping / Wrapping settings:
(Diese werden global für alle folgenden Einträge gesetzt.
Durch Anklicken des Checkbox-Symbols am Zeilenende öffnen sich mehrere Auswahlboxen.)
- Auswahl 1: "Wrap before operators"
- Auswahl 2: "Wrap where necessary"
Line wrapping / Wrapping settings / Other expressions / Assignments:
(Nimmt die vorherige Einstellung für einfache Variablenzuweisungen zurück.)
- Auswahl 1: "Wrap after operators"
Comments:
- Maxium width: 120
- Count width from comments' starting position: [off]
- Enable Javadoc comment formatting: [off]
- Enable block comment formatting: [off]
- Enable line comment formatting: [off]

Die Vorlage wird dann unter dem Namen MyCoRe gespeichert.

Eclipse-Nutzer können sich einfach die Code-Style-Definition herunterladen und importieren
(Anwendungs-Menü: Window → Preferences → Java → Code Style → Formatter).

Javascript-Code Formatierung

Für den Javascript-Editor sind folgende Einstellungen vorzunehmen

Formatierung gemäß den JavaScript-Konventionen
Tabulatoren werden durch Leerzeichen ersetzt
Einrückung mit vier Zeichen
Zeilenumbruch und maximale Zeilenlänge 120

Konfiguration unter Eclipse

Die Einstellung erfolgt unter:

Anwendungs-Menü:
Window → Preferences → Web → Client-side JavaScript → Formatter

Dort wählt man das Profile JavaScript Conventions [built-in] als Vorlage und nimmt folgende Anpassungen vor:

Indentation:
- Tab Policy: Spaces only
- Indentation size: 4 (default)
- Tab size: 4
New Lines:
- At end of file: [on]
Line wrapping:
- Maximum line width: 120
- Default indentation for wrapped lines: 1
- Default indentation for array initializers: 1
- Default indentation for object literal initializers: 1
Comments:
- Maxium width: 120
- Count width from comment's starting position: [off]
- Enable JSDoc comment formatting: [off]
- Enable block comment formatting: [off]
- Enable line comment formatting: [off]

Die Vorlage wird dann unter dem Namen MyCoRe Javascript gespeichert.

Eclipse-Nutzer können sich einfach die Code-Style-Definition herunterladen und importieren
(Anwendungs-Menü: Window → Preferences → Web → Client-side JavaScript → Formatter).

XML-Code Formatierung

Allgemeines

Auch für die Gestaltung von XML-Dateien wurde eine einheitliche Formatierung festgelegt:

Zeilenumbruch und maximale Zeilenlänge 120
Für Einrückungen sind nur Leerzeichen zu verwenden.
Pro Tab sind 2 Zeichen Einrückung vorgesehen.

Konfiguration unter Eclipse

Die Einstellung erfolgt in Eclipse im jeweiligen Projekt unter:

Anwendungs-Menü:
Window → Preferences → XML → XML Files → Editor

Dort wählt man:

Line width: 120
Format Comments [off]
Indent using spaces: [on]
Indentation size: 2

Weiterhin ist die Erkennung von *.xed-Dateien als XML im Editor einzuschalten:

Anwendungs-Menü:
Window → Preferences → General → Editors → File Associations

Dort wird zunächst bei File types: über Add.. der Typ *.xed ausgewählt und anschließend unter Associated editors: über Add.. der XML-Editor mit der Dateiendung verknüpft.

Wenn Ant-Skripte (Datei: build.xml) zum Bauen oder Konfigurieren der Anwendung verwendet werden, muss auch dieser Editor entsprechend den Vorgaben zu XML-Dateien konfiguriert werden. Seine Einstellungen befinden sich unter:

Anwendungs-Menü:
Window → Preferences → Ant → Editor → Formatter

HTML-Code Formatierung

Allgemeines

Auch für die Gestaltung von HTML-Dateien wurde eine einheitliche Formatierung festgelegt:

Zeilenumbruch und maximale Zeilenlänge 120
Für Einrückungen sind nur Leerzeichen zu verwenden.
Pro Tab sind 2 Zeichen Einrückung vorgesehen.

Konfiguration unter Eclipse

Die Einstellung erfolgt unter:

Anwendungs-Menü:
Window → Preferences → Web → HTML Files → Editor

Dort stellt man folgendes ein:

Line width: 120
Indent using spaces: [on]
Indentation size:2

CSS-Code Formatierung

Allgemeines

Für CSS-Dateien gelten dieselben Einstellungen wie für HTML-Dateien:

maximale Zeilenlänge 120
Für Einrückungen sind nur Leerzeichen zu verwenden.
Pro Tab sind 2 Zeichen Einrückung vorgesehen.

Konfiguration unter Eclipse

Die Einstellung erfolgt unter:

Anwendungs-Menü:
Window → Preferences → Web → CSS Files → Editor

Dort stellt man folgendes ein:

Line width: 120
Indent using spaces: [on]
Indentation size:2

Compilieren und Code-Test

Bevor ein Codeteil (Javaklasse, Stylesheet oder Konfigurationsdatei) committed wird, sollte diese gründlich getestet werden. Für Java-Klassen ist als erstes sicher zu stellen, dass sie den Compiler-Lauf erfolgreich bestehen. Um auch Konflikte mit anderen Java-Klassen von vorn herein auszuschließen, sollte vor jedem Commit einer Klasse des MyCoRe-Kerns der Code einmal mittels Maven gebaut werden:

> mvn [-o] clean install

So können Fehler in der Abhängigkeit schneller gefunden werden. Dabei steht -o für Offline. Dies kann genutzt werden, wenn man gerade im Zug oder an ähnlichen Orten entwickelt, wo man offline ist.

Kommentare im Code

Allgemeines

Alle Kommentare sind in Englisch abzufassen. Dabei ist auf allgemein verständliche Sprachkonstrukte zu achten. Der Kommentar soll die kodierten Vorgänge gut beschreiben und für andere nachvollziehbar machen.

Kommentare im Java-Code

Jede Java-Datei hat das nachfolgende Aussehen. Das gestattet ein einheitliches Auftreten des Projektes. Da für alle Dateien mittels JavaDoc automatisch eine Dokumentation generiert wird, ist es Pflicht, die erstellte Klasse mit einer allgemeinen Beschreibung zum Zweck und Einsatz der Klasse zu versehen. Weiterhin sind alle public oder protected Methoden mit einer Beschreibung zu versehen. Hierzu gehört auch die Dokumentation der übergebenen Parameter, der Rückgabewerte und ggf. der geworfenen Exceptions.

Kommentar für eine Java-Klasse:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


/* 
 * This file is part of *** M y C o R e *** 
 * See https://www.mycore.de/ for details. 
 * 
 * This program is free software; you can use it, redistribute it 
 * and / or modify it under the terms of the GNU General Public License 
 * (GPL) as published by the Free Software Foundation; either version 2 
 * of the License or (at your option) any later version. 
 * 
 * This program 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 General Public License for more details. 
 * 
 * You should have received a copy of the GNU General Public License 
 * along with this program, in a file called gpl.txt or license.txt. 
 * If not, write to the Free Software Foundation Inc., 
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307 USA 
 */
 package org.mycore.modules.hello; 
 import java.io.File; 
 /**
  * This class implements methods for ... 
  * 
  * @author Jens Kupferschmidt 
  * @version $Revision: 1.49 $ $Date$ 
  */ 
  public class MCRHello { 
  ... 
  }

Minimaler Kommentar für Java Methoden:

1
2
3
4
5
6
7
8


 
/**
 * This method .. 
 * 
 * @param a the parameter a is the first value. 
 * @return a if it is a positive number, else return 0. 
 */ 
 public final int abs(a) { ... } 

Kommentare in Stylesheets

Auch alle XSLT-Dateien sollen kurze Kommentare enthalten. Unbedingt erforderlich sind auf jeden Fall die Zeilen für die Versionskontrolle. Angestrebt wird folgendes Aussehen eines Stylesheets.

1
2
3
4
5
6
7


<?xml version="1.0" encoding="UTF-8"?>
<!-- ============================================== -->
<!-- $Revision: 1.2 $ $Date$ -->
<!-- ============================================== -->
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  ...
</xsl:stylesheet>

Logging

Alle Logging-Informationen werden, sofern nicht eine Umsetzung mittels der Internationalisierung I18N erfolgt, in Englisch notiert. Für MyCoRe ist das log4j-Paket des Apache-Projektes zu verwenden. Es gib 4 definierte Log-Level mit nachfolgenden Bestimmungen. Es ist davon auszugehen, dass eine normale Anwendung allgemein auf den Level INFO gesetzt ist.

ERROR – Gibt Informationen zu nicht behebbaren Fehlern, z.B. Exceptions, zurück.
WARN – Gibt Informationen zu Fehlern zurück, welche die Weiterarbeit der Anwendung nicht ausschließen. In der Regel wird mit Standardwerten weitergearbeitet.
INFO – Gibt allgemeine Informationen für den normalen Anwender bzw. die Log-Datei aus. Diese Nachrichten haben nur informativen Charakter.
DEBUG – Gibt zusätzliche Informationen, die gezielt durch Einschalten dieses Levels abgerufen werden, aus.