Eclipse-platform
Regels voor naamgeving

Laatst gewijzigd op 26 mei 2006

Regels voor naamgeving en richtlijnen voor het Eclipse-platform:

Java-pakketten

Het Eclipse-platform bestaat uit een verzameling Java-pakketten. De pakketnaamruimte wordt conform de Sun-richtlijnen voor naamgeving van pakketten beheerd; subpakketten mogen niet worden gemaakt zonder toestemming vooraf van de eigenaar van de substructuur van het pakket. De pakketten voor het Eclipse-platform zijn alle subpakketten van org.eclipse. De eerste pakketnaamcomponent na org.eclipse wordt de hoofdpakketnaam genoemd. De volgende hoofdpakketten van org.eclipse zijn toegewezen in de Eclipse 2.0-release:
org.eclipse.ant[.*] - Ondersteuning voor Ant
org.eclipse.compare[.*] - Ondersteuning voor vergelijkingen
org.eclipse.core[.*] - Platformkern
org.eclipse.debug[.*] - Fouten opsporen
org.eclipse.help[.*] - Help-ondersteuning
org.eclipse.jdi[.*] - Eclipse-implementatie van Java-foutopsporingsinterface (JDI)
org.eclipse.jdt[.*] - Java-ontwikkelingstools
org.eclipse.jface[.*] - JFace
org.eclipse.ltk[.*] - Generieke infrastructuur voor taalwerkset
org.eclipse.osgi[.*] - Eclipse-API voor interactie met OSGi
org.eclipse.pde[.*] - Omgeving voor pluginontwikkeling
org.eclipse.search[.*] - Ondersteuning voor zoeken
org.eclipse.swt[.*] - Standaard Widget Toolkit
org.eclipse.team[.*] - Teamondersteuning en versie- en configuratiebeheer
org.eclipse.text[.*] - Framework voor teksteditor
org.eclipse.tomcat[.*] - Ondersteuning voor Apache Tomcat
org.eclipse.ui[.*] - Workbench
org.eclipse.update[.*] - Bijwerken/installeren
org.eclipse.webdav[.*] - Ondersteuning voor WebDAV
De volgende pakketnaamsegmenten zijn gereserveerd:
internal - geeft een intern implementatiepakket aan zonder API's
tests - geeft een non-API-pakket aan dat alleen testsuites bevat
examples - geeft een non-API-pakket aan dat alleen voorbeelden bevat
Deze namen worden gebruikt als kwalificaties en mogen alleen na de hoofdpakketnaam verschijnen. Bijvoorbeeld
org.eclipse.core.internal.resources - Correct gebruik
org.eclipse.internal.core.resources - Onjuist. internal gaat vooraf aan de hoofdpakketnaam.
org.eclipse.core.resources.internal - Onjuist. internal volgt niet onmiddellijk op de hoofdpakketnaam.

Een opmerking over de structuur van het Eclipse-platform: het Eclipse-platform wordt verdeeld in een Core en een gebruikersinterface. Alles dat geclassificeerd is als Core, is onafhankelijk van het venstersysteem; de toepassingen en plugins die afhankelijk zijn van de Core en niet van de gebruikersinterface kunnen headless worden uitgevoerd. Het onderscheid tussen de Core en de gebruikersinterface loopt niet parallel aan het onderscheid tussen API en non-API; zowel Core als gebruikersinterface bevatten API. Het gebruikersinterface-gedeelte van het Eclipse-platform wordt Workbench genoemd. De Workbench is een high-level gebruikersinterfaceframework voor het bouwen van producten met geavanceerde gebruikersinterfaces die zijn gegenereerd op basis van inplugbare componenten. De Workbench wordt bovenop JFace, SWT en de Platform Core gebouwd. SWT (Standard Widget Toolkit) is een low-level, OS-platform-onafhankelijke manier van communiceren met het oorspronkelijke venstersysteem. JFace is een mid-level gebruikersinterfaceframework dat nuttig is voor het genereren van gecompliceerde UI-onderdelen, bijvoorbeeld eigenschapviewers. SWT en JFace zijn per definitie gebruikersinterfaces. Java-tooling is een Java-IDE die boven op de workbench wordt gebouwd. Einde opmerking.

API-pakketten API-pakketten bevatten klassen en interfaces die beschikbaar moeten zijn voor ISV's. De namen van API-pakketten moeten zinvol zijn voor de ISV. Het aantal verschillende pakketten dat de ISV moet onthouden moet klein zijn, omdat een overdaad aan API-pakketten het moeilijk kan maken voor de ISV's om te bepalen welke pakketten moeten worden geïmporteerd. Binnen een API-pakket worden alle openbare klassen en interfaces beschouwd als API. De namen van API-pakketten mogen geen internal, tests of examples bevatten, om verwarring met de naamgeving van non-API-pakketten te voorkomen.

Interne implementatiepakketten Alle pakketten die onderdeel zijn van de platformimplementatie maar geen API bevatten die aan ISV's moet worden blootgesteld, worden beschouwd als interne implementatiepakketten. Alle implementatiepakketten moeten worden gemarkeerd als internal met de tag onmiddellijk na de hoofdpakketnaam. Aan de ISV's wordt kenbaar gemaakt dat alle pakketten die zijn gemarkeerd als internal, taboe zijn. (Een eenvoudige tekstzoekopdracht op ".internal." vindt verdachte verwijzingen in bronbestanden; op dezelfde manier is "internal/" verdacht in .class-bestanden).

Testsuitepakketten  Alle pakketten die testsuites bevatten, moeten worden gemarkeerd als tests met de tag onmiddellijk na de hoofdpakketnaam. Volledig geautomatiseerde testen zijn de norm; dus org.eclipse.core.tests.resources bevat bijvoorbeeld geautomatiseerde testen voor API in org.eclipse.core.resources. Interactieve testen (die hands-on een tester vereisen) moeten worden gemarkeerd als interactive als laatste pakketnaamsegment; bijvoorbeeld org.eclipse.core.tests.resources.interactive bevat de overeenkomende interactieve testen.

Voorbeeldpakketten  Alle pakketten die voorbeelden bevatten die worden verzonden naar ISV's moeten worden gemarkeerd als examples met de tag onmiddellijk na de hoofdpakketnaam. Bijvoorbeeld org.eclipse.swt.examples bevat voorbeelden over hoe SWT API wordt gestart.

Extra regels:

Klassen en Interfaces

De SUN-richtlijnen voor naamgeving schrijven het volgende voor

Klassennamen moeten zelfstandige naamwoorden zijn, met gemengd hoofdlettergebruik waarbij de eerst letter van elk intern woord een hoofdletter is. De klassennamen moeten zo eenvoudig mogelijk en beschrijvend zijn. Gebruik hele woorden en vermijd acroniemen en afkortingen (tenzij de afkorting meer wordt gebruikt dan de lange vorm, zoals bijvoorbeeld URL en HTML).
 
Voorbeelden:
    class Raster;
    class ImageSprite;
 
Interfacenamen moeten met een hoofdletter worden geschreven, net als klassennamen.

Voor interfacenamen wordt de "I" gebruikt vanwege de afspraak voor interface: alle interfacenamen worden voorafgegaan door een "I". Bijvoorbeeld: "IWorkspace" of "IIndex". Deze afspraak is nuttig voor de leesbaarheid van codes, omdat interfacenamen op deze manier herkenbaar zijn. (Microsoft COM-interfaces onderschrijven deze afspraak).

Extra regels:

Methoden

De SUN-richtlijnen voor naamgeving schrijven het volgende voor

Methoden moeten werkwoorden zijn, met gemengd hoofdlettergebruik waarbij de eerste letter een kleine letter is en de eerst letter van elk intern woord een hoofdletter is.
 
Voorbeelden:
    run();
    runFast();
    getBackground();
Extra regels:

Variabelen

De SUN-richtlijnen voor naamgeving schrijven het volgende voor

Voor alle instances, klassen en klassenconstanten, maar niet voor de variabelen, geldt dat voor de namen zowel kleine letters als hoofdletters mogen worden gebruikt. De interne woorden beginnen met hoofdletters. Variabelenamen mogen niet beginnen met het hoofd _ of het dollarteken $, maar deze beide tekens zijn wel in de naam toegestaan.
 
Variabelenamen moeten kort zijn en een zinvolle betekenis hebben. De keuze van een variabelenaam moet verkort zijn; dit betekent dat iemand die toevallig deze naam ziet de bedoeling van de naam kan begrijpen. Variabelenamen die uit één letter bestaan, moeten, behalve voor tijdelijke (weggooi-)variabelen, worden vermeden. Algemene namen voor tijdelijke variabelen zijn: i, j, k, m en n als gehele getallen, en c, d en e als letters.
 
Voorbeelden:
    int i;
    char c;
    float myWidth;

(Opmerking: de afspraak dat niet-constante veldnamen worden voorafgegaan door een "f", bijvoorbeeld "fWidget", geldt hier niet meer)

Constanten

De SUN-richtlijnen voor naamgeving schrijven het volgende voor

De namen van variabelen die zijn gedeclareerd als klassenconstanten en de namen van ANSI-constanten moeten helemaal in hoofdletters worden geschreven, waarbij de woorden worden gescheiden door liggende streepjes ("_").
 
Voorbeelden:
    static final int MIN_WIDTH = 4;
    static final int MAX_WIDTH = 999;
    static final int GET_THE_CPU = 1;

Plugins en extensiepunten

Alle plugins, inclusief de plugins die onderdeel zijn van het Eclipse-platform, bijvoorbeeld Resources- en Workbench-plugins, moeten unieke ID's hebben waarvoor dezelfde regels voor naamgeving gelden als voor de Java-pakketten. Workbenchplugins bijvoorbeeld krijgen de naam org.eclipse.ui[.*].

De pluginnaamruimte wordt hiërarchisch beheerd; maak geen plugin zonder toestemming vooraf van de eigenaar van de insluitende naamruimte.

Extensiepunten die meerdere extensies verwachten, moeten een naam in meervoudsvorm krijgen. Bijvoorbeeld "builders" en niet "builder".