Wie markiere ich logische Codeabschnitte in Java-Kommentaren?

Java-Klassen werden im Allgemeinen in logische "Blöcke" unterteilt. Gibt es eine Konvention zur Kennzeichnung dieser Abschnitte? Idealerweise wird es von den wichtigsten IDEs unterstützt.

Ich persönlich benutze diese Methode:

//// Section name here ////

Einige Redakteure scheinen jedoch Probleme damit zu haben.

In Objective-C-Code können Sie beispielsweise diese Methode verwenden:

#pragma mark -
#pragma mark Section name here

Dies führt zu einem Menü in XCode, das folgendermaßen aussieht:

Ich persönlich verwende 80-Zeichen-Zeilentrennzeichen wie folgt:

public class Client {

    //================================================================================
    // Properties
    //================================================================================

    private String name;
    private boolean checked;

    //================================================================================
    // Constructors
    //================================================================================

    public Client() {
    }

    public Client(String name, boolean checked) {
        this.name = name;
        this.checked = checked;
    }

    //================================================================================
    // Accessors
    //================================================================================

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public boolean isChecked() {
        return checked;
    }

    public void setChecked(boolean checked) {
        this.checked = checked;
    }

}

Natürlich mag dies für ein so kleines POJO etwas übertrieben erscheinen, aber glauben Sie mir, es hat sich in einigen großen Projekten als sehr nützlich erwiesen, in denen ich große Quelldateien durchsuchen und schnell die Methoden finden musste, an denen ich interessiert war. Es hilft auch zu verstehen die Quellcodestruktur.

In Eclipse habe ich eine Reihe von benutzerdefinierten Vorlagen erstellt (Java -> Editor -> Vorlagen im Dialogfeld "Einstellungen" von Eclipse), die diese Balken generieren, z. - sepa (SEParator für Accessoren) - sepp (SEParator für Eigenschaften) - sepc (SEParator für Konstruktoren) - usw.

Ich habe auch die Standardvorlage "Neue Klasse" geändert (Java -> Codestil -> Codevorlagen im Bildschirm "Eclipse-Einstellungen").

Außerdem gibt es ein altes Eclipse-Plugin namens Coffee-Bytes , das die Art und Weise verbessert, wie Eclipse Teile des Codes faltet. Ich weiß nicht, ob es noch funktioniert, aber ich erinnerte mich, dass man beliebige faltbare Zonen definieren könnte, indem man spezielle Kommentare wie // [ABSCHNITT] oder so hinzufügt. Möglicherweise funktioniert es in den letzten Eclipse-Versionen noch. Schauen Sie sich das an.

Für Intellij / Android Studio gibt es eine erstaunliche Lösung.
Beginnen Sie mit:
//region Description
und enden Sie mit:
//endregion

Die Verknüpfung dazu befindet sich im Menü, das Sie mit Command+ Alt+ T(Mac) oder Ctrl+ Alt+ T(Windows) öffnen können.

Sie können bei Bedarf auch eine eigene Linie für eine zusätzliche visuelle Trennung hinzufügen. Die Region kann wie jede Funktion mit den Tasten +/- nach Belieben verkleinert und erweitert werden. Sie können auch mit Command+ Alt+ Period( Ctrl+ Alt+ Period) zwischen Regionen navigieren.

Quelle .

Beispiel:

//region Parceler Implementation
//---------------------------------------------------------------------------------------
@Override
public int describeContents() {
    return 0;
}

@Override
public void writeToParcel(Parcel dest, int flags) {
    dest.writeParcelable(this.die, 0);
    dest.writeParcelable(this.dieSprite, 0);
}

private DieVm(Parcel in) {
    this.die = in.readParcelable(Die.class.getClassLoader());
    this.dieSprite = in.readParcelable(Sprite.class.getClassLoader());
}

public static final Parcelable.Creator<DieVm> CREATOR = new Parcelable.Creator<DieVm>() {
    public DieVm createFromParcel(Parcel source) {
        return new DieVm(source);
    }

    public DieVm[] newArray(int size) {
        return new DieVm[size];
    }
};
//---------------------------------------------------------------------------------------
//endregion

Eclipse definiert eine Javadoc-Annotation @category (scrollen Sie zu dem Abschnitt "Category Support"), der das Filtern nach Kategorien in der Gliederungsansicht ermöglicht. Nicht genau das, was Sie wollen. Ich bin überrascht, dass niemand ein Eclipse-Plugin geschrieben hat, das eine Ansicht wie Ihren Screenshot bietet.

Das hat mir auch gefallen, als ich xcode verwendet habe. Für Eclipse verwende ich Strg + O (Kurzübersicht), um durch eine Java-Klasse zu navigieren.

Die Verwendung unnötiger Kommentare / Markierungen im Code zur Unterstützung der Arbeit ist möglicherweise keine gute Vorgehensweise. Ich habe wenig Ahnung von der Entwicklung von Xcode und Java, aber alle wichtigen IDEs, die die Mitglieder ohne spezielle Markierungen wie Eclipse unterstützen, zeigen die Methoden und Mitglieder mithilfe der Gliederungsansicht, die mit ctrl+OIntellij ausgelöst werden kann (ich bevorzuge die Verwendung von mehr auf Mac und hatte eine Community Edition) hat das gleiche Gliederungskonzept und kann mit (Strg + F12) schnell aufgerufen werden. Mein Punkt hier ist also, keine unnötigen Markierungen im Code zu verwenden, da alle (oder zumindest guten / vernünftigen) IDEs dies automatisch tun können.

Soweit ich weiß, gibt es keine unterstützte Spezifikation für die Gruppierung von Klassenmitgliedern. Sie können eine beliebige Kommentarkonvention verwenden, die Sie mögen, aber wahrscheinlich wird sie von keinem Tool unterstützt.

Es ist besser, verwandte Mitglieder durch Vererbung oder Aggregation in separate Klassen zu gruppieren. Dies wird als guter OOP-Stil angesehen

Zusätzlich zu Andreys Antwort zur Verwendung von // region // endregion fügen wir [BigAscii-Buchstaben] [1] in wichtige Codeabschnitte ein. Beim schnellen Scrollen fällt es wirklich auf. Ein Nachteil dieses Ansatzes ist, dass ich nicht danach suchen kann, sodass Sie einen Suchbegriff direkt unter dem "Banner" hinzufügen müssen, wie ich es unten tue.

Blockquote

//    _      _____          _____                  _   _
//   | |    |  __ \   /\   |  __ \      /\        | | | |
//   | |    | |  | | /  \  | |__) |    /  \  _   _| |_| |__
//   | |    | |  | |/ /\ \ |  ___/    / /\ \| | | | __| '_ \
//   | |____| |__| / ____ \| |       / ____ \ |_| | |_| | | |
//   |______|_____/_/    \_\_|      /_/    \_\__,_|\__|_| |_|
//
//   Search here with: LDAP Auth

[1]: http://patorjk.com/software/taag/#p=display&c=c%2B%2B&f=Big&t=LDAP Auth

Ich würde Javadoc verwenden ; oder verwenden Sie Folgendes als einfaches "Trennzeichen" (einzelne oder 3 Zeilen):

/** RecyclerOnItemClickListener */

/** 
 * RecyclerOnItemClickListener
 */

Damit es in IDE in einer anderen Farbe als dem unauffällig kommentierten Grau erscheint.

Mit einer modernen IDE können Sie Ihren Code auf viele verschiedene Arten anzeigen und sogar neu organisieren. Mit Eclipse können Sie sogar die Definition des Codes, auf den Sie den Cursor setzen, in einem anderen Bereich anzeigen.

Jede automatische Neuorganisation Ihres Codes führt dazu, dass ein solches Markup zusammenbricht.

Wenn Sie eine Gruppierung wünschen, sollten Sie in Betracht ziehen, Dinge, die zu derselben Klasse gehören, und Dinge, die nicht zu verschiedenen Klassen gehören, zusammenzufassen.

Wenn Sie Ihre Methoden gruppieren können, führen Sie eine andere Klasse speziell für das Konzept aus, das Sie in einem Abschnitt erfassen möchten. Das Erstellen von Dateien ist kostenlos.

Für IntelliJ mag ich:

        public void ________________INIT__________________() {};

sieht in der Dateistruktur hübsch aus!