Dokumentation

🚧

Diese Seite befindet sich in Bearbeitung

🚧

🤓

Diese Seite ist eine Bewertungsrichtlinie, die ab Blatt 1 annotiert und ab Blatt 2 abgezogen wird.

🤓

Beschreibung

Genauso wichtig wie funktionierender Quellcode, ist es, diesen auch richtig zu Dokumentieren. Dazu gibt es einige Grundlagen und Richtlinien:

Unnötige Aussagen

Entwicklerkommentare, die triviales aussagen oder Kommentare, in denen nicht für den Quellcode relevante informationen beinhalten, gelten als unnötige Aussagen. Auch Beschwerden bezüglich des Checkstyle sind unnötige Aussagen, die dem Quellcode keinen Mehrwert bieten, die entfernt werden sollten. Als grobe Richtlinie gilt hier: Kommentare sollten genau die Stellen erklären, die eine erfahrene Person nicht ohne weiteres beim ersten Durchlesen verstehen kann.

Auskommentierter Code

Gerne schreiben wir uns kleine Zeilen als Sanity-Check um die Abarbeitung innerhalb einer Methode zu überprüfen und ggf. nach Fehlern zu suchen. Wenn wir allerdings diese Test-Hilfen nicht mehr benötigen, reicht es nicht, diese einfach in ein Kommentar umzuwanden oder einen Kommentarblock um einen Quellcode-Abschnitt zu setzen. Dieser auskommentierte Quellcode behindert den Lesefluss. Aus diesem Grund ist es vorzuziehen, Codestellen, die nicht benötigt werden, zu entfernen.

TODO/FIXME's

Auch ist es manchmal sinnvoll, sich bestimmte Codestellen, die noch bearbeitet oder repariert werden sollen mit entsprechenden Tags zu versehen. Hierfür werden die Tags TODO und FIXME für Kommentare zur Verfügung gestellt. Diese werden in den IDE's wiefolgt gesammelt angezeigt um die Suche zu vereinfachen:

IntelliJ

Am linken Rand des Programms gibt es ein Feld das "TODO" heißt. Sollte das noch nicht da sein, kann dieses einfach in dem "..."-Symbol gefunden werden (oben links). Alternativ kann dieses auch gefunden werden mit einem schnellen Doppelklick auf "shift". Dadurch wird eine Suchzeile geöffnet, in der dann einfach nach "TODO" gesucht werden kann.

Eclipse

In Eclipse kann diese Ansicht unter Window -> Show View -> Tasks angezeigt werden. Es ist dann dort, wo auch die Problems und Console Tabs sind.

Wenn das Program fertig entwickelt ist, oder zur korrektur abgegeben wird, sollten diese Kommentare entfernt werden, unabhängig davon, ob der Code zukünftig noch bearbeitet werden soll oder nicht.

Generell gilt: Code soll in sauberer, leserlicher Form sein und in vollständiger und aufgeräumter Form abgegeben werden.

Negativbeispiel

// TODO auto-generated method stub
public EncounterResult executeEncounter(Player player, Monster monster) {
    // Get the attack strength of the monster and deal a corresponding amount of damage to the player
    player.takeDamage(monster.getAttackStrength());
    // If the player has died...
    if (player.isDead()) {
        // ... return the variant "PLAYER_DIED" of the ennum "EncounterResult"
        // Checkstyle forces me to use the ugly underscore in "PLAYER_DIED"
        return EncounterResult.PLAYER_DIED;
    }
 
    // TODO include the damage multiplier of the player's weapon
    monster.takeDamage(player.getAttackStrength());
    if (monster.isDead()) {
        // System.out.println("Monster died");
        return EncounterResult.MONSTER_DIED;
    }
 
    // FIXME choose a better name than "TIE"
    return EncounterResult.TIE;
}

Positivbeispiel

public EncounterResult executeEncounter(Player player, Monster monster) {
    // The monster attacks first...
    player.takeDamage(monster.getAttackStrength());
    if (player.isDead()) {
        return EncounterResult.PLAYER_DIED;
    }
 
    // .. and then the player attacks
    monster.takeDamage(player.getAttackStrength());
    if (monster.isDead()) {
        return EncounterResult.MONSTER_DIED;
    }
 
    return EncounterResult.TIE;
}