Comment marquer des sections logiques de code dans les commentaires Java?
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 soutenu par les principaux IDE.
J'utilise personnellement cette méthode:
//// Section name here ////
Cependant, certains éditeurs semblent avoir des problèmes avec cela.
Par 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:
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 projets énormes où j'ai dû parcourir de gros fichiers source 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 Préférences 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 souviens que l'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 récentes révisions d'Eclipse, alors jetez un œil.
Pour intellij/Android studio, il existe une solution étonnante.
Commencer avec://region Description
et se terminent par://endregion
Le raccourci pour cela se trouve dans le menu que vous pouvez ouvrir avec Command+Alt+T (Mac) ou Ctrl+Alt+T (Les fenêtres)
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
Eclipse définit un @ annotation javadoc de catégorie (faites défiler jusqu'à la section intitulée "Prise en charge des catégories") qui permet le filtrage par catégorie dans la vue d'ensemble. Pas exactement ce que tu veux. Je suis surpris que personne n'ait écrit un plugin Eclipse qui offre une vue comme votre capture d'écran.
J'ai aimé ça aussi quand j'utilisais xcode. Pour Eclipse, j'utilise ctrl + o (aperçu rapide) pour naviguer dans une classe Java.
L'utilisation de commentaires/marqueurs inutiles dans le code pour faciliter le travail peut ne pas être une bonne pratique. J'ai peu d'idée sur xcode et Java mais tous les principaux soutiens de l'EDI trouvant les membres sans aucun marqueur spécial comme Eclipse montrent les méthodes et les membres utilisant la vue d'ensemble qui peuvent être déclenchés en utilisant ctrl+O, Intellij (que je préfère utiliser davantage sur mac et qui avait aussi une édition communautaire) a le même concept de contour et est rapidement accessible en utilisant (ctrl + f12). Donc mon point ici est de ne pas utiliser de balisage inutile dans le code car tous (ou au moins bons/sains) les IDE peuvent le faire automatiquement.
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 commentaires que vous souhaitez, 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 OOP
En plus de la réponse d'Andrey fournie, pour utiliser // region // endregion, nous insérons [lettres BigAscii] [1] dans les principales sections de code. Lors d'un défilement rapide, il se démarque vraiment. Un inconvénient de cette approche est que je ne peux pas la 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
J'utiliserais javadoc ; ou utilisez ce qui suit comme un simple "séparateur" (simple ou 3 lignes):
/** RecyclerOnItemClickListener */
/**
* RecyclerOnItemClickListener
*/
De sorte qu'en IDE il apparaît dans une couleur différente autre que le gris discret commenté.
Un IDE moderne vous permet d'afficher votre code de différentes manières, et même de le réorganiser. Eclipse vous permet même d'afficher 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 les éléments appartenant à la même classe et les éléments n'appartenant pas à des classes différentes.
Si vous pouvez regrouper vos méthodes, faites une autre classe spécifiquement pour ce concept que vous souhaitez capturer dans une section. Allez-y, la création de fichiers est gratuite.