Plateforme Eclipse
Conventions de dénomination

Dernière révision : 24 juin 2002 - Version d'Eclipse Project R2.0

Conventions de dénomination et instructions pour la plateforme Eclipse :

Packages Java

La plateforme Eclipse est constituée d'une collection de packages Java. L'espace nom du package est géré conformément aux instructions de dénomination Sun Sun's package naming guidelines qui spécifient qu'aucun sous-package ne doit être créé sans accord préalable du propriétaire de la sous-arborescence du package. Les packages de la plateforme Eclipse sont tous des sous-packages org.eclipse. Le premier composant du nom du package après org.eclipse est appelé le nom du package majeur. Les principaux packages suivants d'org.eclipse sont affectés dans l'édition Eclipse 2.0 :
org.eclipse.ant[.*] : support d'Ant
org.eclipse.compare[.*] : support de comparaison (Compare)
org.eclipse.core[.*] : core de la plateforme
org.eclipse.debug[.*] : débogage (Debug)
org.eclipse.help[.*] : support de l'aide
org.eclipse.jdi[.*] : implémentation de l'interface de débogage Java (JDI) dans Eclipse
org.eclipse.jdt[.*] - outils de développement Java
org.eclipse.jface[.*] : JFace
org.eclipse.pde[.*] : JDE (Plug-in Development Environment)
org.eclipse.search[.*] : support de recherche
org.eclipse.swt[.*] : SWT (Standard Widget Toolkit)
org.eclipse.team[.*] - Support d'équipe et gestion des versions et de la configuration
org.eclipse.tomcat[.*] - Support d'Apache Tomcat
org.eclipse.ui[.*] : plan de travail
org.eclipse.update[.*] - Mise à jour/Installation
org.eclipse.webdav[.*] : support WebDAV
Les segments de nom de package suivants sont réservés :
internal : indique un package d'implémentation interne qui ne contient pas d'API.
tests : indique un package qui ne contient pas d'API, mais uniquement des scénarios de test.
examples : indique un package qui ne contient pas d'API, mais uniquement des exemples.
Ces noms sont utilisés comme qualificatifs et doivent apparaître uniquement après le nom du package majeur. Par exemple :
org.eclipse.core.internal.resources : usage correct.
org.eclipse.internal.core.resources : incorrect. internal précède le nom du package majeur.
org.eclipse.core.resources.internal : incorrect. internal ne suit pas immédiatement le nom du package majeur.
Aparté sur la structure de la plateforme Eclipse : celle-ci se divise en Core (API principale) et en UI (interface utilisateur). Tout ce qui est classifié comme "Core" est indépendant du système de fenêtre ; les applications et les plug-ins qui dépendent de l'API principale et non de l'interface utilisateur peuvent s'exécuter sans tête. La distinction entre Core et UI n'est pas comparable avec celle qui existe entre API et non-API ; Core et UI contiennent des API. La partie interface utilisateur de la plateforme Eclipse est connue sous le nom de plan de travail. Il s'agit d'une structure d'interface utilisateur de haut niveau permettant la génération de produits avec des interfaces utilisateur sophistiquées basées sur des composants pouvant recevoir des plug-in. Le plan de travail est généré au sommet de JFace, SWT et de l'API principale de la plateforme. SWT (Standard Widget Toolkit) est un moyen de bas niveau, indépendant de la plateforme du système d'exploitation qui permet de parler au système de fenêtrage natif. JFace est une structure d'interface utilisateur de niveau intermédiaire, utile à la génération de sections d'interface utilisateur complexes, tels que les afficheurs de propriétés. SWT et JFace sont par définition des interfaces utilisateur. Les outils Java sont un IDE Java généré au sommet du plan de travail. Fin de l'aparté.

Packages d'API : ce sont ceux qui contiennent des classes et des interfaces devant être mis à la disposition des fournisseurs indépendants de logiciels. Les noms des packages d'API doivent avoir un sens pour ces fournisseurs. Le nombre de packages différents dont les fournisseurs doivent se rappeler doit être petit, car savoir quels packages ils doivent importer peut être rendu difficile par la profusion des packages d'API disponibles. Dans un package d'API, toutes les interfaces et les classes publiques sont considérées comme des API. Les noms des packages d'API ne doivent pas contenir les mots internal, tests ou examples afin d'éviter toute confusion avec le schéma de dénomination des packages non-API.

Packages d'implémentation interne : tous les packages faisant partie de l'implémentation de la plateforme, mais qui ne contiennent pas d'API devant être exposée aux fournisseurs indépendants de logiciels, sont considérés être des packages d'implémentation interne. Tous les packages d'implémentation doivent contenir internal juste après le nom du package majeur. Les fournisseurs seront avertis que tous les packages marqués internal sont hors limites. (Une simple recherche sur ".internal." détecte les références suspectes dans les fichiers source, tout comme "/internal/" est suspect dans les fichiers .class).

Packages de scénario de test : tous les packages contenant des scénarios de test doivent contenir tests juste après le nom du package majeur. Généralement, les tests sont totalement automatisés. Ainsi, par exemple, org.eclipse.core.tests.resources doit contenir des tests automatisés pour API dansorg.eclipse.core.resources. Les tests interactifs (ceux qui requièrent un testeur disponible) doivent être marqués interactive dans le dernier segment du nom du package. Par exemple, org.eclipse.core.tests.resources.interactive contient les tests interactifs correspondants.

Packages d'exemples : tous les packages contenant des exemples qui sont envoyés aux fournisseurs indépendants de logiciels doivent contenir examples juste après le nom du package majeur. Par exemple, org.eclipse.swt.examples contient des exemples sur le mode d'utilisation des API SWT.

Règles supplémentaires :

Classes et interfaces

Le document Sun's naming guidelines indique que :

les noms de classe doivent être des noms en majuscules et minuscules, dont la première lettre de chaque mot interne doit être une lettre capitale. Utilisez des noms de classe simples et descriptifs. Utilisez des mots entiers : évitez les acronymes et les abréviations (à moins que l'utilisation de l'abréviation soit largement plus étendue, URL ou HTML par exemple).
 
Exemples :
    class Raster;
    class ImageSprite;
 
Les noms d'interface doivent porter une majuscule initiale tout comme les noms de classe.

Pour les noms d'interface, nous suivons la convention "I"-pour-interface : tous les noms d'interface commencent par "I". Par exemple, "IWorkspace" ou "IIndex". Cette convention facilite la lisibilité du code en rendant les noms d'interface plus facilement reconnaissables. (Les interfaces Microsoft COM adhèrent à cette convention).

Règles supplémentaires :

Méthodes

Le document Sun's naming guidelines indique que :

les méthodes doivent être des verbes en majuscules et minuscules, dont la première lettre de chaque mot interne doit être une lettre capitale.
 
Exemples :
    run();
    runFast();
    getBackground();
Règles supplémentaires :

Variables

Le document Sun's naming guidelines indique que :

excepté les variables, toutes les instances, classes et constantes de classe sont en minuscules et majuscules avec la première lettre en minuscule. Les mots internes commencent par une majuscule. Les noms de variable ne doivent pas commencer par un trait de soulignement _, ni par le signe dollar $, même si ces deux caractères sont autorisés.
 
Les noms de variable doivent être courts, tout en demeurant significatifs. Le choix d'un nom de variable doit être une mnémonique, conçue pour indiquer à l'observateur le but de son utilisation. Les noms de variable composés d'un seul caractère doivent être évités, sauf pour les variables "jetables" temporaires. Les noms courants de variables temporaires sont : i, j, k, m et n pour les entiers, c, d et e pour les caractères.
 
Exemples :
    int i;
    char c;
    float myWidth;

(Remarque : nous ne suivons plus la convention qui ajoute le préfixe "f" aux noms de zones non constantes, tel que "fWidget".)

Constantes

Le document Sun's naming guidelines indique que :

les noms des constantes de classes variables déclarées et des constantes ANSI doivent être en majuscules et que les mots doivent être séparés par des traits de soulignement ("_").
 
Exemples :
    static final int MIN_WIDTH = 4;
    static final int MAX_WIDTH = 999;
    static final int GET_THE_CPU = 1;

Plug-in et points d'extension

Tous les plug-in, y compris ceux qui font partie de la plateforme Eclipse, comme les plug-ins de ressources et du plan de travail, doivent avoir un identificateur unique respectant le même modèle de dénomination que les packages Java. Par exemple, les plug-ins du plan de travail s'appellent org.eclipse.ui[.*].

L'espace de nom du plug-in est géré de manière hiérarchique. Ne créez pas de plug-in sans accord préalable du propriétaire de l'espace de nom de délimitation.

Les points d'extension qui attendent plusieurs extensions doivent porter des noms au pluriel. Par exemple, "builders" plutôt que "builder".