Comment marquer des sections logiques de code dans les commentaires Java?


92

Les classes Java sont généralement divisées en "blocs" logiques. Existe-t-il une convention pour marquer ces sections? Idéalement, il serait pris en charge par les principaux IDE.

J'utilise personnellement cette méthode:

//// Section name here ////

Cependant, certains éditeurs semblent avoir des problèmes avec cela.

À titre d'exemple, dans le code Objective-C, vous pouvez utiliser cette méthode:

#pragma mark -
#pragma mark Section name here

Cela se traduira par un menu dans XCode qui ressemble à ceci:

texte alternatif


4
en tant que développeur iOS, c'est ce qui m'a le plus manqué quand j'ai commencé avec Android Studio
Chris Chen

1
contre-voté: avec les IDE et les langues modernes, c'est une mauvaise pratique. Si vous devez sectionner votre code, vous enfreignez probablement déjà le principe de responsabilité unique et il est préférable de se diviser en différentes classes / fichiers. S'il y a plusieurs éditeurs, il sera probablement désynchronisé après un certain temps de toute façon, comme certains le suivront, certains refactoriseront et réorganiseront le code, ou les actions automatiques d'enregistrement et de formatage le casseront.
f.carlsen

contre-voté: je suis d'accord avec @ f.carlsen. Si vous structurez votre classe avec des commentaires, vous risquez fort de rompre le principe de responsabilité unique .
schrieveslaach

Pour les haters: appelez-moi lorsque Java prend en charge les extensions de classe de style Swift où vous pouvez logiquement séparer vos implémentations d'interface en différentes sections. Et oui, une classe peut bien implémenter plusieurs interfaces en même temps.
William Entriken

Réponses:


66

J'utilise personnellement des séparateurs de ligne de 80 caractères, comme ceci:

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;
    }

}

Bien sûr, cela peut sembler un peu exagéré pour un si petit POJO, mais croyez-moi, cela s'est avéré très utile dans certains grands projets où je devais parcourir de gros fichiers sources et trouver rapidement les méthodes qui m'intéressaient. Cela aide également à comprendre la structure du code source.

Dans Eclipse, j'ai créé un ensemble de modèles personnalisés (Java -> Editeur -> Modèles dans la boîte de dialogue Préférences d'Eclipse) qui génèrent ces barres, par exemple. - sepa (SEParator for Accessors) - sepp (SEParator for Properties) - sepc (SEParator for Constructors) - etc.

J'ai également modifié le modèle standard "nouvelle classe" (Java -> Style de code -> Modèles de code dans l'écran des préférences d'Eclipse)

En outre, il existe un ancien plugin Eclipse appelé Coffee-bytes , qui a amélioré la façon dont Eclipse replie des parties de code. Je ne sais pas si cela fonctionne toujours, mais je me suis souvenu qu'on pouvait définir des zones pliables arbitraires en ajoutant des commentaires spéciaux, comme // [SECTION] ou quelque chose. Cela pourrait encore fonctionner dans les dernières révisions d'Eclipse, alors jetez un œil.


145

Pour intellij / android studio, il existe une solution incroyable.
Commencez par:
//region Description
et terminez par:
//endregion

Le raccourci pour cela se trouve dans le menu que vous pouvez ouvrir avec Command+ Alt+ T(Mac) ou Ctrl+ Alt+ T(Windows)

Vous pouvez également ajouter votre propre ligne pour une séparation visuelle supplémentaire si vous en avez besoin. La région peut être contractée et étendue à volonté avec les boutons +/- comme n'importe quelle fonction. Vous pouvez également naviguer entre les régions avec Command+ Alt+ Period( Ctrl+ Alt+ Period)

Source .

Exemple:

//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

C'est incroyablement utile Merci Andrey. BTW J'utilise la disposition des raccourcis clavier éclipse et je ne pense pas que les raccourcis fonctionnent pour moi, mais la '// région' fonctionne très bien
ThinkBonobo

2
Je ne vois aucun moyen pour que cela apparaisse dans la vue de la structure, donc j'utilise toujours de faux membres vides (avec supprimer l'avertissement inutilisé).
Tom

1
existe-t-il un moyen d'afficher ces régions dans Android Studio (vue Structure)?
MiguelHincapieC

Link est mort; ce blog IntelliJ IDEA peut être une référence utile. Il mentionne également les éléments de pliage de style NetBeans <editor-fold ...> .
Franklin Yu

la meilleure réponse
Michał Ziobro

14

Eclipse définit une annotation javadoc @category ( faites défiler jusqu'à la section marquée "Prise en charge des catégories") qui permet le filtrage par catégorie dans la vue d'ensemble. Pas exactement ce que vous voulez. Je suis surpris que personne n'ait écrit un plugin Eclipse qui offre une vue comme votre capture d'écran.


Dans la plupart des vues java, cependant, il est possible de filtrer les membres de la classe en fonction de leurs catégories, afin de les masquer comme getters et setters par défaut, par exemple.
Riduidel

Je ne sais pas pourquoi je ne peux pas utiliser @category dans Android Studio, savez-vous ce que je peux faire pour obtenir le même comportement?
MiguelHincapieC

6

J'aimais ça aussi quand j'utilisais xcode. Pour eclipse, j'utilise ctrl + o (aperçu rapide) pour naviguer dans une classe Java.


6

L'utilisation de commentaires / marqueurs inutiles dans le code pour aider à travailler peut ne pas être une bonne pratique. J'ai peu d'idée sur le développement de xcode et java, mais tous les principaux IDE soutiennent la recherche de membres sans marqueurs spéciaux comme eclipse montre les méthodes et les membres utilisant la vue d'ensemble qui peut être déclenchée en utilisant ctrl+O, Intellij (que je préfère utiliser plus sur mac et avait un Community Edition aussi) a le même concept de plan et peut être rapidement accessible en utilisant (ctrl + f12). Donc, mon point ici est de ne pas utiliser de balisage inutile dans le code car tous les IDE (ou au moins bons / sains) peuvent le faire automatiquement.


2
D'accord, les marqueurs de section ne font qu'ajouter à l'encombrement visuel. Votre classe doit être suffisamment concentrée pour que ces choses soient irréversibles.
Paul McKenzie

15
Bien sûr, mais le fait de regrouper les méthodes en sections logiques et délimitées peut aider à imposer un ordre visuel à ce qui serait autrement une liste plate de méthodes. Parfois, vous ne savez pas exactement quelle méthode vous voulez, et il est agréable de prendre en compte les méthodes associées en même temps, et d'avoir une idée que vous voyez toute l'étendue du code associé.
Brian Rak

4

Pour autant que je sache, il n'existe pas de spécification prise en charge pour regrouper les membres de la classe. Vous pouvez utiliser la convention de commentaire de votre choix, mais il est probable qu'elle ne sera prise en charge par aucun outil.

Il est préférable de regrouper les membres liés dans une classe distincte via l'héritage ou l'agrégation. Ceci est considéré comme un bon style POO


5
Le fractionnement de sections de code ne semble possible qu'en théorie. Par exemple, prenez une classe Client avec des attributs tels que le nom et une collection «factures». Je serais ravi de pouvoir diviser cela en une section "nom" qui contient des getters / setters pour le nom et une section "factures" qui contient des méthodes d'ajout / suppression pour les factures. Il semble peu pratique de les diviser en une hiérarchie de classes qui ne peut ajouter qu'un seul attribut par classe, à savoir "NamedEntity", "NameAndAddressEntity", "Invoicable", ...
Frederik

3

En plus de la réponse d'Andrey, pour utiliser // region // endregion, nous insérons des [lettres BigAscii] [1] dans les sections de code principales. Lorsque vous faites défiler rapidement, cela se démarque vraiment. Un inconvénient de cette approche est que je ne peux pas le rechercher, vous devez donc ajouter un terme de recherche juste en dessous de la "bannière" comme je le fais ci-dessous.

Blockquote

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

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


3

J'utiliserais javadoc ; ou utilisez ce qui suit comme simple "séparateur" (simple ou 3 lignes):

/** RecyclerOnItemClickListener */

/** 
 * RecyclerOnItemClickListener
 */

De sorte que dans l'IDE, il apparaît dans une couleur différente autre que le gris commenté discret.


2

Un IDE moderne vous permet de visualiser votre code de différentes manières, et même de le réorganiser. Eclipse vous permet même de visualiser la définition du code sur lequel vous avez le curseur dans un autre panneau.

Toute réorganisation automatique de votre code entraînera la rupture de ce balisage.

Si vous souhaitez regrouper, envisagez de regrouper des éléments appartenant à la même classe et des éléments n'appartenant pas à des classes différentes.


0

Si vous pouvez regrouper vos méthodes, effectuez une autre classe spécifiquement pour ce concept que vous souhaitez capturer dans une section. Allez-y, la création de fichiers est gratuite.


-18

Pour IntelliJ j'aime:

        public void ________________INIT__________________() {};

joli dans la structure du fichier!


3
Cela semble être une très mauvaise solution. Pourquoi déclarer des méthodes supplémentaires lorsque votre objectif est l'organisation du code?
nsg

1
C'est pour rendre le fichier entier segmenté dans la vue Structure.
Tycho Pandelaar

1
ce n'est que celui qui regarde vraiment dans le studio Android, propose
toi

13
La pire chose que j'aie jamais vue !! et c'est PUBLIC! o_O
Cocorico

3
C'est la seule réponse qui apparaît dans la vue de la structure et qui fonctionne avec différents IDE. Rendez-le privé et souriez et supportez-le, ou ne l'utilisez pas si vous ne l'aimez pas, mais ne cachez pas cette réponse aux autres lecteurs en la rejetant dans l'oubli.
Tom
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.