Eclipse-plattformen
Navngivningsregler

Sist endret 26. mai 2006

Navngivningsregler og retningslinjer for Eclipse-plattformen:

Java-pakker

Eclipse-plattformen består av en samling med Java-pakker. Pakkenavneområdet blir styrt i samsvar med Suns retningslinjer for pakkenavngivning, underpakker skal ikke opprettes uten forhåndssamtykke fra eieren av pakkens deltre. Pakkene for Eclipse-plattformen er alle underpakker av org.eclipse. Den første pakkenavnkomponenten etter org.eclipse kalles hovedpakkenavnet. Følgende hovedpakker i org.eclipse blir tildelt i Eclipse 2.0-utgaven:
org.eclipse.ant[.*] - Ant-støtte
org.eclipse.compare[.*] - Sammenlikningsstøtte
org.eclipse.core[.*] - Plattformkjerne
org.eclipse.debug[.*] - Feilsøking
org.eclipse.help[.*] - Hjelpefunksjon
org.eclipse.jdi[.*] - Eclipse-implementering av JDI (Java Debug Interface)
org.eclipse.jdt[.*] - Java-utviklingsverktøy
org.eclipse.jface[.*] - JFace
org.eclipse.ltk[.*] - Infrastruktur for generisk språkverktøy
org.eclipse.osgi[.*] - Eclipse-API for interaksjon med OSGi
org.eclipse.pde[.*] - PDE (Plug-in Development Environment)
org.eclipse.search[.*] - Søkestøtte
org.eclipse.swt[.*] - Standard Widget Toolkit
org.eclipse.team[.*] - Gruppestøtte og versjons- og konfigurasjonsadministrasjon
org.eclipse.text[.*] - Ramme for tekstredigeringsprogram
org.eclipse.tomcat[.*] - Apache Tomcat-støtte
org.eclipse.ui[.*] - Arbeidsbenk
org.eclipse.update[.*] - Oppdatere/installere
org.eclipse.webdav[.*] - WebDAV-støtte
Følgende pakkenavnsegmenter er reserverte:
internal - indikerer en intern implementeringspakke som ikke inneholder en API
tests - indikerer en ikke-API-pakke som bare inneholder testpakker
examples - indikerer en ikke-API-pakke som bare inneholder eksempler
Disse navnene blir brukt som kvalifikatorer og kan bare stå etter hovedpakkenavnet. Eksempel:
org.eclipse.core.internal.resources - Riktig bruk
org.eclipse.internal.core.resources - Feil. internal står foran hovedpakkenavnet.
org.eclipse.core.resources.internal - Feil. internal følger ikke direkte etter hovedpakkenavnet.

I tillegg til hvordan Eclipse-plattformen er strukturert: Eclipse-plattformen er delt inn i Core og UI. Alt som er klassifisert som Core (kjerne), er uavhengig av vindussystemet. Applikasjoner og plugin-moduler som er avhengig av kjernen og ikke av UI (brukergrensesnittet) kan kjøres i kommandogrensesnittet. Forskjellen på Core og UI er ikke det samme som forskjellen på API og ikke-API. Både Core og UI inneholder API. UI-delen av Eclipse-plattformen kalles en arbeidsbenk. Arbeidsbenken er et UI-rammeverk på høyt nivå for bygging av produkter med avanserte brukergrensesnitt bygd fra pluggbare komponenter. Arbeidsbenken blir bygd på toppen av JFace, SWT og plattformkjernen. SWT (Standard Widget Toolkit) er en OS-plattform-uavhengig måte å snakke til interne vindussystemer på lavt nivå på. JFace er et UI-rammeverk på mellomnivå som er nyttig for bygging av komplekse UI-deler som for eksempel egenskapsvisninger. SWT og JFace er per definisjon UI. Java-verktøyet er en Java-IDE bygd på toppen av arbeidsbenken.

API-pakker API-pakker er pakker som inneholder klasser og grensesnitt som må gjøres tilgjengelig for ISVer. Navnene på API-pakkene må være forståelige for ISV. Antall forskjellige pakker som ISV må huske, bør være lite, fordi en overflod av API-pakker gjør det vanskelig for ISVer å vite hvilke pakker de skal importere. I en API-pakke blir alle felles pakker og grensesnitt betraktet som API. Navnene på API-pakker bør ikke inneholde internal, tests, eller examples, for å unngå sammenblanding med skjemaet for navngivning av ikke-API-pakker.

Interne implementeringspakker  Alle pakker som er del av plattformimplementeringen, men som ikke inneholder noe API som skal vises for ISVer, blir betraktet som interne implementeringspakker. Alle implementeringspakker bør flagges som internal, med koden rett etter hovedpakkenavnet. ISVer får beskjed om at alle pakker som er merket internal, er utenfor grensene. (Et enkelt tekstsøk etter .internal." oppdager mistenkelige referanser i kildefilene. På samme måte er "/internal/" mistenkelig i .class-filer).

Pakker med testpakker  Alle pakker som inneholder testpakker, bør merkes som tests, med koden rett etter hovedpakkenavnet. Fullstendig automatiserte tester er det vanlige, slik at for eksempel org.eclipse.core.tests.resources vil inneholde automatiserte tester for APIer i org.eclipse.core.resources. Interaktive tester (som krever en manuell tester) bør flagges med interactive som siste pakkenavnsegment, slik at for eksempel org.eclipse.core.tests.resources.interactive vil inneholde de tilsvarende interaktive testene.

Eksempelpakker  Alle pakker som inneholder eksempler som leveres til ISVer, bør flagges som examples, med koden rett etter hovedpakkenavnet. For eksempel org.eclipse.swt.examples vil inneholde eksempler på hvordan du bruker SWT-APIen.

Andre regler:

Klasser og grensesnitt

Suns retningslinjer for navngivning sier følgende:

Klassenavn skal være substantiver med både store og små bokstaver, med stor forbokstav i hvert interne ord. Prøv å bruker enkle og beskrivende klassenavn. Bruk hele ord - unngå akronymer og forkortelser (hvis ikke forkortelsen er mer brukt enn den lange formen, for eksempel URL eller HTML).
 
Eksempler:
    class Raster;
    class ImageSprite;
 
Navn på grensesnitt skal har store bokstaver på samme måte som klassenavn.

For grensesnittnavn (interface) følger vi konvensjonen "I" for interface: alle grensesnittnavn har prefikset "I". For eksempel "IWorkspace" eller "IIndex". Denne konvensjonen gjør det enklere å lese koden, fordi grensesnittnavn gjenkjennes lettere. (Microsoft COM-grensesnitt følger denne konvensjonen).

Andre regler:

Metoder

Suns retningslinjer for navngivning sier følgende:

Metoder skal være verb med både store og små bokstaver, med liten forbokstav, men med stor forbokstav i hvert interne ord.
 
Eksempler:
    run();
    runFast();
    getBackground();
Andre regler:

Variabler

Suns retningslinjer for navngivning sier følgende:

Alle forekomster, klasser og klassekonstanter, bortsett fra variabler, har både store og små bokstaver, med liten forbokstav. Interne ord begynner på store bokstaver. Variabelnavn skal ikke begynne med understrekingstegn _ eller dollartegn $ , selv om begge deler er tillatt.
 
Variabelnavn skal være korte, men meningsfulle. Variabelnavnets valg skal være bokstavelig - det vil si at brukeren skal forstå hva det skal brukes til. Du bør unngå variabelnavn på bare en bokstav, bortsett fra i midlertidige bruk-og-kast-variabler. Vanlige navn for midlertidige variabler er i, j, k, m og n for heltall, og c, d og e for tegn.
 
Eksempler:
    int i;
    char c;
    float myWidth;

(Merk: Vi følger ikke lenger konvensjonen med å sette prefiksen "f" foran ikke-konstante feltnavn, for eksempel "fWidget".)

Konstanter

Suns retningslinjer for navngivning sier følgende:

Navn på variabeldeklarerte klassekonstanter og ANSI-konstanter, skal bare ha store bokstaver, bortsett fra ord skilt av understreking ("_").
 
Eksempler:
    static final int MIN_WIDTH = 4;
    static final int MAX_WIDTH = 999;
    static final int GET_THE_CPU = 1;

Plugin-moduler og utvidelsespunkter

Alle plugin-moduler, inkludert de som er del av Eclipse-plattformen, for eksempel plugin-modulene Ressurser og Arbeidsbenk, må ha unike IDer som følger samme navngivningsmønster som Java-pakker. Plugin-moduler for arbeidsbenk heter for eksempel org.eclipse.ui[.*].

Plugin-modulen for navneområde blir styrt hierarkisk. Ikke opprett plugin-moduler uten forhåndstillatelse fra eieren av det innkapslende navneområdet.

Utvidelsespunkter som forventer flere utvidelser, bør ha navn i flertall. For eksempel "builders" i stedet for "builder".