Java-Doc – es ist ein absolutes MUSS!

6. Juli 2021 - Lesezeit: 4 Minuten

Durch Dinge wie CleanCode oder dem KISS-Prinzip versuchen wir unseren Code möglichst verständlich zu halten. Wir benennen Methoden nachdem was sie tun, wissen, dass eine Methode auch nur eine Sache machen soll und auch die Benamung unserer Variablen sind sprechend.

Wer das alles konsequent berücksichtigt, der wird in den meisten Fällen keine Kommentare im Quelltext hinterlassen müssen – so zumindest der Wortlaut vieler Dozenten und Autoren.

In der Praxis sieht das oft aber ganz anders aus.

In vielen Unternehmen gibt es “Code-Styles” – quasi Arbeitsanweisungen wie zum Beispiel die Banamung von Variablen und Methoden vorzunehmen ist. Da gibt es Verfechter der ungarischen Notation (einer String-Variable wird dann mit ein “s” vorangestellt, z.B. sName) oder andere, völlig wilde, Anweisungen. Auch die zu verwendende Sprache spielt eine Rolle. Variablen auf deutsch und Methoden in englisch vielleicht? Oder anders herum? Oder alles auf englisch?

Sicher ist vieles davon eine Glaubensfrage und abhängig davon, wer den Code zu sehen bekommt.

Ich bin der Ansicht, dass alles was offensichtlich ist, keinen Kommentar benötigt. Eine Methode die tatsächlich auch nur eine Aufgabe durchführt, z.B. sprechende Variablen nutzt und es offensichtlich ist, dass sie auch nur das macht wie der Name suggeriert, wird keinen zusätzlichen Kommentar benötigen.

private int addiere(final int ersteZahl, final int zweiteZahl) {
  return ersteZahl + zweiteZahl;
}

An diesem, zugegebenermaßen sehr einfachen, Beispiel lässt sich sehr gut darstellen, dass in einem solchen Fall wohl kein Kommentar notwendig ist. Die Methode tut was sie verspricht und es ist auf den ersten Blick klar, was am Ende dabei herauskommt.

Natürlich sind die auftretenden, alltäglichen Anwendungsgebiete in den meisten Fällen nicht so einfach zu lösen. Besonders dann nicht, wenn unterschiedliche Menschen am gleichen Code arbeiten. Der Eine hat vielleicht irgendwann einmal eine solch einfache Methode geschrieben. Der zweite hat diese dann um ein Logging erweitert; der Dritte dann um dies und das, usw. Am Ende bekommt man, vielleicht nach Jahren, eine Methode vor die Nase, die man ursprünglich mal selbst geschrieben hat, aber jetzt kaum wiedererkennen kann.

Spätestens jetzt ist entweder ein Refactoring angebracht (wenn die Methode z.B. nun etwa viel mehr macht, als nur addieren) oder – wenn das möglicherweise zu invasiv ist – mindestens aber ein Java-Doc um zu verdeutlichen, was die Methode nun macht. Generell darf soetwas aber eigentlich nicht passieren – also eigentlich (Stichwort: Überlagern von Methoden).

Besonderes Augenmerkt ist geboten, wenn die Methode bereits über einen Kommentar verfügt. Hier besteht natürlich die Gefahr, dass jemand Anpassungen vorgenommen hat, diese aber im Kommentar nicht berücksichtigt hat. So entsteht schnell ein sinnloser Kommentar und an dieser Stelle wäre kein Kommentar sogar sinnvoller.

In jedem Fall ist es meiner Meinung nach aber unerlässlich, mindestens der Klasse ein Java-Doc zu verpassen. Hier ist Platz um zu verdeutlichen, was die eigentliche Aufgabe der Klasse ist. Wofür ist sie da, was beinhaltet sie und wofür stellt sie Methoden bereit? Genau hier ist der richtige Platz. Hier schreibt man seinen Namen rein, damit jeder weiß, wer die Klasse ursprünglich erstellt hat und an wen man sich bei Fragen dann auch wenden kann:

package de.magicmarcy;

/**
 * Klasse um eine Person mit ihren Eigenschaften abzubilden. Diese
 * Klasse stellt u.a. Methoden zu Berechnung des Alters oder zur 
 * Ermittlung des BMI zur Verfügung.
 *
 * @author   magicmarcy
 * @version  01.01.2020
*/

public class Person {
  private String name;
  private String vorname;
  private Anschrift anschrift;
  private Telefon telefon;
  private Date geburtsdatum;

  public Person() {
...
}

Da die meisten IDEs in der Lage sind, alle verfügbaren Methoden übersichtlich aufzulisten ist es an dieser Stelle sogar nicht einmal notwendig, die Methoden im JavaDoc zu erwähnen.

In diesem Beispiel habe ich eigene Objekte für die Anschrift und Telefone verwendet. Da diese nun ebenfalls über ein JavaDoc verfügen kann ich sehr schnell sehen, was das Anschrift-Objekt für Eigenschaften hat um darauf entsprechend zugreifen zu können. Die Eigenschaften Name und Vorname benötigen hier sicherlich am wenigsten einen eigenen Kommentar oder gar eine Dokumentation. Ja, ich habe hier natürlich sehr triviale Beispiele gewählt und in der Praxis ist es eben nicht immer so leicht wie hier. Dennoch denke ich, dass das Beispiel zeigt, dass auch ein JavaDoc durchaus seine Daseinsberechtigung hat. Im Zweifel lieber ein bisschen mehr dokumentieren und sich die Zeit nehmen, seine Variablen und Methoden eindeutig zu benennen. Ein anderer kann nicht in deinen Kopf schauen, wenn er vor deinem Code sitzt und vielleicht weißt auch du in 5 Jahren nicht mehr so genau, was du da eigentlich mal gemacht hast.