Java Doc mehrere Return Parameter

[MiMa]

Ich habe in der Methode in der ich ein String Datum verarbeite und ein Array zurück gebe.
Ich würde aber gerne in der Java Doc auch alle Parameter mit einbringen die im Array Zurück gegeben werden.

Aktuell sieht die Dokumentation in IntelliJ wie folgt aus

Ermittelt das Datum, die Uhrzeit und prüft es auf Echtheit.
Params:     datum – : String (dd.mm.yyyy, dd.mm.yyyy hh:mm:ss:SS)
Returns: datumArray : String[]

Ich würde das aber gerne so haben wollen

/**
     * Ermittelt das Datum, die Uhrzeit und prüft es auf Echtheit.<br>
     *
     * @param datum : <b>String</b> (dd.mm.yyyy, dd.mm.yyyy hh:mm:ss:SS)
     * @return datumArray : <b>String[]</b>
     * @return datumArray [0] Datum (dd.MM.yyyy, ungültig)
     * @return datumArray [1] Uhrzeit (HH:mm:ss)
     * @return datumArray [2] DatumUhrzeit (dd.MM.yyy HH:mm:ss)
     * @return datumArray [3] Tag (dd)
     * @return datumArray [4] Monat (MM)
     * @return datumArray [5] Jahr (yyyy)
     * @return datumArray [6] Stunde (HH)
     * @return datumArray [7] Minute (mm)
     * @return datumArray [8] Sekunde (ss)
     * @return datumArray [9] Millisekunden (1365407280000)
     */

Wäre das möglich?

Danke

 

[Robert Zenz]

Nein, es ist auch nicht ratsam wie du es machst, absolut nicht. Du transportierst hier sehr viel zusammenhaengende Information ohne diese "richtig" zu strukturieren. Du solltest all das in eine Klasse zusammenfassen und diese retournieren, dann eruebrigen sich jeglichen Fragen zum Wert welcher zurueck geliefert wird.

Nehmen wir mal deine jetzige Implementierung fuer ein Beispiel:

String[] datumArray = datumZerlegen(datum);

System.out.println("Heute ist der " + datumArray[4] + ". Tag.");

Schnell, ohne oben hinzusehen, ist der Code richtig?

Jetzt koennte man natuerlich sagen "Ja, aber ich mache dafuer Konstanten":

public final int DATUM_INDEX = 0;
public final int UHRZEIT_INDEX = 1;
public final int DATUM_UHRZEIT_INDEX = 2;
public final int TAG_INDEX = 2;
public final int MONAT_INDEX = 3;
public final int JAHR_INDEX = 4;
public final int STUNDE_INDEX = 5;
public final int MINUTE_INDEX = 6;
public final int SEKUNDE_INDEX = 7;

String[] datumArray = datumZerlegen(datum);

System.out.println("Heute ist der " + datumArray[TAG_INDEX] + ". Tag.");

Schnell, ohne oben hinzusehen, ist der Code richtig?

Mach' "einfach" eine Klasse daraus, dann hast du all diese Probleme nicht:

Datum zerlegtesDatum = datumZerlegen(datum);

System.out.println("Heute ist der " + zerlegtesDatum.getTag() + ". Tag.");

 

[MiMa]

Dies ist so zu sagen eine Grundmethode 'sucheFormate(String datum) : String[]'
in der Klasse Datum 'sucheFormate' oder ausserhab der Klasse 'Datum.sucheFormate(....)'
was bei meinen Grundmethoden in der Regel nicht vorkommt.

Ich nutze diese Grundmethode um Anwendungmethoden zu erstellen die ich
dann bei der Programmierung verwende wie diese kleinen.

/**
     * Ermittelt das Jahr aus einem Datum.<br>
     *
     * @param datum : <b>String</b>(dd.mm.yyyy)
     * @return jahr : <b>String</b> (yyyy)
     */
    // sucheJahr(String datum) : String pFunk
    public static String sucheJahr(String datum) {
        String[] datumArray = sucheFormate(datum);
        String jahr = datumArray[5];
        LOG.info("Das gefundene und geprüfte Jahr ist : " + jahr);
        return jahr;
    } // sucheJahr

/**
     * Prüft ein Datum auch Echtheit.<br>
     *
     * @param datum <b>String</b> (dd.mm.yyyy)
     * @return datum <b>String</b> (dd.mm.yyyy)
     */
    public static String pruefen(String datum) {
        String[] datumArray = new String[9];
        datumArray = sucheFormate(datum);
        datum = datumArray[0];
        LOG.info("Das geprüfte Datum ist : " + datum);
        return datum;
    } // pruefen

Das habe ich mir deshalb so überlegt, da ich sonst ziemlich viel doppelten Code
in meinen Methoden hätte.

 

[LimDul]

Wenn du das so umbaust, wie @Robert Zenz vorschlägt, hast du ja auch keinen doppelten Code.

Anstelle von

datumArray = sucheFormate(datum);
datum = datumArray[0];

Hast du dann

ZerlegtesDatum datumZerlegt = sucheFormate(datum);
datum = datumZerlegt.getDatum();

Und ist deutlich lesbarer verständlicher, als warum da eine 0 steht oder im anderen Code eine 5.

Grundsätzlich sollte gemäß Clean Code der Anspruch an alle Funktionen sein:
* Sie sind ohne Kommentar verständlich.

Jeder Kommentar den man schreibt, ist in Clean Code ein Eingeständnis, dass man es nicht geschafft hat verständlichen, lesbaren Code zu schreiben. (Gibt natürlich Ausnahmen - APIs die Dritten bereitgestellt werden, sollte man z.B. dokumentieren).

 

[Robert Zenz]

Ja schau mal, wenn du eine Klasse verwenden wuerdest braeuchstest du diese Hilfsmethoden doch gar nicht mehr.

int jahr = datumZerlegen(datum).getJahr();

Also klar kannst du deine datumZerlegen behalten (aber wenn die auch Pruefungen macht waere sowas wie "validiereUndZerlege" besser), aber diese sollte eben deine Werte in einer Klasse zurueck liefern.

public class Datum {
    public int getJahr();
    public int getTag();
    public int getMonat();
    public int getStunde();
   // ...
}

 

[Robert Zenz]

Jeder Kommentar den man schreibt, ist in Clean Code ein Eingeständnis, dass man es nicht geschafft hat verständlichen, lesbaren Code zu schreiben. (Gibt natürlich Ausnahmen - APIs die Dritten bereitgestellt werden, sollte man z.B. dokumentieren).

Erstens, japp. Zweitens, die APIs Dritter kann man auch im eigenen Projekt wrappen und damit wegkapseln, was ich sehr gerne mache weil man damit dann einfach nur mit der eigenen API arbeitet und auch unabhaengiger ist wenn der Dritte etwas aendert. Das minimiert dann auch Verstaendnisprobleme im eigenen Code.

 

[LimDul]

Mir ging es jetzt um den Fall, wenn man eine API schreibt, die man Dritten Bereitstellt - die gehört logischerweise dokumentiert.

 

[MiMa]

Ja ihr habt recht, eine eigene Klasse zu machen würde sicher einiges leichter machen.
Meine Methode sucheFormate() war im Grunde eine einfache Methode mit einem Rückgabewert und hieß auch mal anders.
Sie ist nach und nach angestiegen und bei zwei oder drei Rückgabewerte wollte ich den Aufwand einer eigenen Klasse
für das finden von Datumsformate nicht machen.
Allerdings ist der Funktionsumfang deutlich angestiegen und die Methode ist auch sehr umfangreich geworden.

Ich bin kein Profi Programmierer und lerne quasi immer noch, da ich leider hin und wieder pausen einräumen muss.
Da ich gerne Programmiere und das als Hobby für den eigenen Bedarf mache, kann ich nicht Tag für Tag Programmieren
was ich allerdings gerne tun würde und mir so viel Zeit nehme wie ich kann.
Ich konnte wegen Corona Infektion und Schlaganfall ein Jahr nicht Programmieren, was ich jetzt langsam wieder angehe.

Ich weis noch wie es geht und leider fallen mir einige Dinge nicht mehr ein, die ich dann auch leider wieder nachholen.
Auch versuche ich alles mit Struktur und übersichtlich zu gestalten.
Demnach habe ich eine Klasse mit den Namen Datum in der ich alle Methoden gepackt habe die zur Verarbeitung
von Datums notwendig sind. Ich ergänze die Klasse Datum dann mit Variablen, Get -und Set-Methoden.

Ich bin wirklich froh das hier im Forum so freundliche Menschen sind die einen gerne weiterhelfen.

 

[Neumi5694]

Es gibt nur einen Return-Parameter.
Eine eigene Klasse z.B. in Form eines Records wäre auf jeden Fall die beste Lösung, vor allem auch, weil deine Datentypen sonst ziemlicher Murks sind.
Falls du aber tatsächlich alle einzelnen Felder eines Arrays einer Rückgabe dokumentieren willst, kannst du das so machen:

/**
 * @return Array: <b>String[]</b>
 * <li> [0] Datum (dd.MM.yyyy, ungültig)
 * <li> [1] Uhrzeit (HH:mm:ss)
 * <li> [2] DatumUhrzeit (dd.MM.yyy HH:mm:ss)
...
*/

Nicht schön, aber selten

 

[MiMa]

Danke für die Information.
Ich bin mir noch am überlegen, wie ich das am besten löse.
Die Klasse Datum, in der meine eigenen Methoden implementiere sind ohne Variablen, Getter und Setter das es in einem Projekt welches ich eigens als Bibliothek verwende. Dort landen alle meine Methoden die ich in anderen Programmen verwende. Oft wird dies dann als JAR Bibliothek eingebunden. Ich bin mir nicht sicher, ob ich in dieser Klasse Variablen Getter und Setter implementieren sollte um dann auch das Problem eleganter zu lösen?

 

[Neumi5694]

Geter auf jeden Fall. Wenn die Werte nur einmalig beim Erstellen gesetzt werden, braucht es keine Setter.
Ansonsten sind diese grundsätzlich auch anzulegen.
Was ich bei records nicht mag, ist, dass die Getter kein "get" als Präfix haben und das das Record public Zugriff auf die Variablen erlaubt.. Da sind selbst angelegte Klassen schöner.

 

[MiMa]

Ich habe das Problem wie vorgeschlagen als eigene Klasse "Datum" mit Variablen Get -und Set Methoden sowie spezielle Methoden umgesetzt.

Vielen Dank für die Unterstützung.