Code Style Conventions

Da jeder Entwickler seine eigenen Präferenzen hat, was die Namensgebung, Formatierung und Konventionen hat, können größere Softwareprojekte sehr schnell sehr unübersichtlich werden. Daher haben wir einige wichtige Regeln festgelegt, wie Projekte aufgebaut und formatiert, und Code geschrieben werden soll.

Unser oberstes Prinzip ist das KISS Prinzip, ein Akronym, dass für Keep it simple, stupid! steht, und so viel bedeutet, wie das der Code so simple und verständlich geschrieben werden sollte, wie Möglich. Sideeffects sollten vermieden werden, das Early Return Pattern genutzt, und generell für eine gute Lesbarkeit gesorgt werden. Code, der diesem Prinzip folgt, ist (fast) immer besser lesbar.

Ein weiterer wichtiger Bestandteil unserer Konventionen ist das YAGNI Prinzip, was ebenfalls ein Akronym ist, aber für You ain't gonna need it steht. Nach diesem Prinzip sollte das Overengineering so gut es geht vermieden werden und Software minimal gehalten werden. YAGNI geht Hand in Hand mit dem KISS-Prinzip.

Project Conventions

Jedes Projekt sollte so minimal wie möglich gehalten werden und nur die beschriebenen Funktionen enthalten. Entwickelt man zum Beispiel ein Ban-System, so sollte dieses nur Funktionen enthalten, die notwendig sind, z.B. Ban, Kick, Mute, aber keinen Teamchat. Strukturell folgen Projekte einem immer gleichen Schema (Beispiel aus einem bestehenden Projekt):

.
├── build.gradle.kts
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── README.md
├── settings.gradle.kts
└── src
    ├── main
    │   ├── java
    │   │   └── net
    │   │       └── wandoria
    │   │           └── dungeons
    │   │               ├── api
    │   │               │   ├── BossStartEvent.java
    │   │               │   └── LootChestOpenEvent.java
    │   │               ├── listener
    │   │               │   └── DungeonEnvironmentListener.java
    │   │               ├── party
    │   │               │   ├── DungeonParty.java
    │   │               │   └── PartyStatus.java
    │   │               └── WandoriaDungeons.java
    │   └── resources
    │       └── paper-plugin.yml
    └── test
        ├── java
        └── resources

Als Build System sollte zumeist Gradle verwendet werden, soweit nicht anders festgelegt. Für Namen von Packeten gilt die Schreibweise net.wandoria.<namenspace>, also wie im obrigen Beispiel net.wandoria.dungeons als Basispacket. Auf eine Klasse mit dem Namen Main sollte verzichtet werden und diese durch eine Klasse mit dem Namen des Projektes ersetzt werden. Bitte nutzte keine statische Instanz innerhalb dieser Klasse, wie zum Beispiel

public static WandoriaDungeons INSTANCE;

sondern verwende stattdessen Dependency Weitergabe

package net.wandoria.dungeons.party;

import net.wandoria.dungeons.WandoriaDungeons;
import org.jetbrains.annotations.NotNull;

public class TestClazz {
    private final WandoriaDungeons wandoriaDungeons;

    // Die Main Klasse wird in die Klasse injected
    public TestClazz(@NotNull WandoriaDungeons wandoriaDungeons) {
        this.wandoriaDungeons = wandoriaDungeons;
    }
}

Code Conventions

Damit der Code über alle Projekte einheitlich und übersichtlich ist, gibt es einige wichtige Stilregeln für Code. Wir orientieren uns fast ausschließlich am Google Java Styleguide:

Classes

Klassen sollten einen einfach verständlichen Namen haben und nur die Funktionen erfüllen, die notwendig sind. Der Name einer Klasse sollte im Camel-Case geschrieben werden - also DungeonParty, anstelle von Dungeonparty. Aus dem Namen der Klasse sollte der Zweck hervorgehen.

Variables

Bitte benutze static nur dort, wo es wirklich notwendig ist!. Statische Werte sollten nur für Konstanten ohne Sideeffects verwendet werden und in Großbuchstaben geschrieben werden, also zum Beispiel public static int MAX_PLAYERS = 10;. Für die Namensgebung von sonstigen anderen Variablen sollte lowerCamelCase verwendet werden, also userCoins, anstelle von usercoins oder UserCoins. Bitte gebe Variablen eine gute Beschreibung und verwende für magische Zahlen beschriebene Konstanten. Für bereits vorhandene Konstanten wie PI sollten die von Java bereits vorgegebenen Konstanten benutzt werden!

Methods

Eine Methode sollte immer nur genau eine Funktion ausführen und am besten so wenige Sideeffects wie möglich haben. Im Namen der Methode sollte angegeben sein, was diese Funktion genau macht. Methoden werden von der Namensgebung wie Variablen gehandhabt.

Comments

Kommentare sind eine der einfachsten Möglichkeiten, Code verständlich für alle zu halten. Kommentare sollten immer auf Englisch geschrieben werden. Es gibt zwei wesentliche Arten von wichtigen Kommentaren: JavaDocs und normale Kommentare.

JavaDocs

JavaDocs sind spezielle Kommentare, die diesem Schema folgen:

/**
 * Das ist eine JavaDoc Kommentar
 */

Diese Kommentare könnnen für andere Entwickler sehr wichtige Informationen enthalten, zum Beispiel, wie welche Variablen verwendet werden, welche Sideeffects die Funktion hat, und was die Funktion genau wie macht:

    /**
 * Calculates the sum of two integers, if the first integer is 42, the 
 function returns the product of the two integers instead.
 *
 * @param x The first integer
 * @param y The second integer
 * @return The sum of both integers, or the product if x = 42
 */
public int calculateSum(int x, int y) {
    if (x == 42) {
        return x * y;
    }
    return x + y;
}

IDEs wie Intellij übersetzten diese Kommentare direkt und können somit Tooltips anzeigen. Erstelle solche Kommentare am besten direkt beim Erstellen der Funktion, um es später nicht zu vergessen. Bitte dokumentiere die Edgecases deiner Funktionen!

Oracle JavaDoc Explanation

Normal Comments

Normale Kommentare sind wichtig, um innerhalb von längeren Methoden den Überblick zu bewahren, es muss aber nicht jede einzelne Zeile kommentiert werden, verwende sie mit Bedacht.

Git Conventions

Git ist eines der wichtigsten Tools für die Entwicklung an Projekten. Hier findest du einige wichtige Tipps:

Git Branching Strategy

Um eine vernünftige Arbeit mit anderen Entwicklern zu gewährend und einen sauberen Git Tree zu erhalten, sollte eine vernünftige Branching Strategie verwendet werden. Bitte pushe niemals direkt auf den main Branch eines Repositories. Der main Branch dient einem Zweck - und nur einem Zweck - nämlich die derzeitige stabile Version des Projektes dazustellen. Über zum Beispiel Pipelines werden Pushes auf diesen Branch meist direkt auf den Server übertragen und veröffentlicht. Er dient als Failsafe, falls das Projekt aus irgendeinem Grund auf einem anderen Branch nicht mehr funktioniert.

Natürlich müssen Änderungen am Code vorgenommen werden, hierfür bieten sich Feature und Development Branches an. Feature Branches werden mit feat, Development Branches mit dev abgekürzt. Ein Branch für ein Feature mit dem Namen Bossroom wäre also feat/bossroom, welcher von einem dev Branch abgeleitet ist. Der Tree würde also so aussehen:

feat/bossroom -> dev -> main

und wird auch in dieser Reihenfolge zusammengeführt. Sollte das Feature stabil sein, wird es per Pull-Request mit dem Development Branch, und anschließen der Development Branch mit dem Main Branch zusammengeführt, lasse immer eine zweite Person über den Code schauen - man nennt dies ein Review - vier Augen sehen mehr als zwei.

Grade in der Anfangsphase der Entwicklung eines Features, in dem die Pipeline noch nicht aufgesetzt ist, kann der Development Branch auch weggelassen werden, muss aber spätestens mit der ersten stabilen Version des Main Branches verwendet werden. Ist die Githistorie deiner Änderungen nicht nachvollziehbar oder schlecht, werden deine Änderungen gegebenenfalls nicht akzeptiert.

Other Important Things

Bitte verwende so oft wie Möglich die Jetbrains Annotations und bei Bedarf Lombok. Solltest du Probleme mit Gradle haben, empfiehlt sich der Gradle Guide.

Last Words

Du hast es erfolgreich durch unseren Code Styleguide geschafft. Herzlichen Glückwunsch! Sollten Fragen offenbleiben, kannst du dich jederzeit an einen Entwickler wenden, wir helfen dir gerne weiter :)

29 September 2025