Eclipse-platform
Navngivningsregler

Sidst revideret den 26. maj 2006

Navngivningsregler og -retningslinjer for Eclipse-platformen:

Java-pakker

Eclipse-platformen består af en samling af Java-pakker. Pakkenavneområdet styres i overensstemmelse med Suns retningslinjer for navngivning af pakker. Underpakker bør ikke oprettes uden forudgående godkendelse fra ejeren af pakkeundertræet. Pakkerne til Eclipse-platformen er alle underpakker til org.eclipse. Den første pakkenavnskomponent efter org.eclipse kaldes det primære pakkenavn. Der er følgende primære pakker af org.eclipse i Eclipse 2.0:
org.eclipse.ant[.*] - Ant-understøttelse
org.eclipse.compare[.*] - Understøttelse af sammenligning
org.eclipse.core[.*] - Platformskerne
org.eclipse.debug[.*] - Fejlfinding
org.eclipse.help[.*] - Hjælp
org.eclipse.jdi[.*] - Eclipse-implementering af JDI (Java Debug Interface)
org.eclipse.jdt[.*] - Java-udviklingsværktøjer
org.eclipse.jface[.*] - JFace
org.eclipse.ltk[.*] - Infrastruktur for generisk sprogværktøj
org.eclipse.osgi[.*] - Eclipse-API for interaktion med OSGi
org.eclipse.pde[.*] - Plugin-udviklingsmiljø
org.eclipse.search[.*] - Understøttelse af søgning
org.eclipse.swt[.*] - Standard Widget Toolkit
org.eclipse.team[.*] - Understøttelse af team og versions- og konfigurationsstyring
org.eclipse.text[.*] - Teksteditorstruktur
org.eclipse.tomcat[.*] - Understøttelse af Apache tomcat
org.eclipse.ui[.*] - Arbejdsbænk
org.eclipse.update[.*] - Opdatering/installation
org.eclipse.webdav[.*] - WebDAV-understøttelse
Følgende pakkenavnssegmenter er reserverede:
internal - En intern implementeringspakke, der ikke indeholder noget API.
tests - En ikke-API-pakke, der kun indeholder testrækker.
examples - En ikke-API-pakke, der kun indeholder eksempler.
Disse navne anvendes som kvalifikatorer, og de må kun optræde efter det primære pakkenavn. Eksempel:
org.eclipse.core.internal.resources - Korrekt brug.
org.eclipse.internal.core.resources - Forkert. internal kommer før det primære pakkenavn.
org.eclipse.core.resources.internal - Forkert. internal kommer ikke lige efter det primære pakkenavn.

Bemærkning til strukturen i Eclipse-platformen: Eclipse-platformen er opdelt i en Code (kerne) og en UI (brugergrænseflade). Alt, der er klassificeret som Core, er uafhængigt af vinduessystemet. Programmer og plugins, der er afhængige af Core og ikke af UR, kan udføres uden hovede. Forskellen mellem Core og UI ligner ikke forskellen mellem API og ikke-API - både Core og UI indeholder API. Brugergrænsefladedelen i Eclipse-platformen kaldes Arbejdsbænk. Arbejdsbænken er en brugergrænseflade på højt niveau til bygning af produkter med avancerede brugergrænseflader, der kan bygges fra plugin-komponenter. Arbejdsbænken er bygget oven på JFace, SWT og platformskernen. SWT (Standard Widget Toolkit) er en måde at kommunikere med det indbyggede vinduessystem på lavt niveau og uafhængigt af styresystemsplatformen. JFace er et brugergrænsefladeområde på mellemniveau, der anvendes til at bygge komplekse brugergrænsefladedele som f.eks. egenskabsfremvisere. SWT og JFace er pr. definition UI. Java-værktøjet er en Java-IDE bygget ovenpå arbejdsbænken. Slut på bemærkning.

API-pakker  API-pakker indeholder klasser og grænseflader, der skal være tilgængelige for ISV'er. Navnene på API-pakker skal være forståelige for ISV'en. Det bør være et lille antal forskellige pakker, ISV skal huske, fordi overflødige pakker kan gøre det vanskeligt for ISV'er at vide, hvilke pakker der skal importeres. I en API-pakke betragtes alle offentlige klasser og grænseflader som API. Navnene på API-pakker bør ikke indeholder internal, tests eller examples for at undgå sammenblanding med skemaet til navngivning af ikke-API-pakker.

Interne implementeringspakker  Alle pakker, der er en del af platformsimplementeringen, men som ikke indeholder API, der skal udsættes for ISV'er, betragtes som interne implementeringspakker. Alle implementeringspakker skal markeres som internal. Koden skal optræde lige efter det primære pakkenavn. ISV'er får besked på, at alle pakker, der er mærket med internal, er forbudt område. (En enkel tekstsøgning efter ".internal." registrerer mistænkelige referencer i kildefiler. På samme måde er "/internal/" mistænkelig i .class-filer).

Pakker med testsamlinger  Alle pakker, der indeholder testsamlinger, skal markeres som tests med koden placeret lige efter det primære pakkenavn. Fuldautomatiske test er det normale, så org.eclipse.core.tests.resources indeholder for eksempel automatiske API-test i org.eclipse.core.resources. Interaktive test (test, der kræver en aktiv tester) skal markeres med interactive som det sidste pakkenavnssegment. Dvs. at f.eks. org.eclipse.core.tests.resources.interactive indeholder de tilhørende interaktive test.

Pakker med eksempler  Alle pakker, der indeholder eksempler, som leveres til ISV'er, skal markeres som examples med koden placeret lige efter det primære pakkenavn. F.eks. kan org.eclipse.swt.examples indeholde eksempler på, hvordan SWT API anvendes.

Yderligere regler:

Klasser og grænseflader

Suns retningslinjer for navngivning

Klassenavne skal være navneord, hvor det første bogstav i alle interne ord skal skrives med stort. Forsøg at gøre klassenavnene enkle og beskrivende. Brug hele ord. Undgå akronymer og forkortelser (medmindre forkortelsen anvendes oftere end den lange form, f.eks. URL eller HTML).
 
Eksempler:
    class Raster;
    class ImageSprite;
 
Navne på grænseflader skal skrives med store bogstaver på samme måde som klassenavne.

I forbindelse med grænsefladenavne bruger vi "I"-for-Interface-reglen: Der sættes et "I" foran alle grænsefladenavne. Eksempel: "IWorkspace" eller "IIndex". Denne regel gør det lettere at læse koden, fordi navne på grænseflader hurtigere genkendes. (Microsoft COM-grænseflader følger denne regel).

Yderligere regler:

Metoder

Suns retningslinjer for navngivning

Metoder skal være udsagnsord, hvor det første bogstav er skrevet med lille, og hvor det første ord i alle interne ord er skrevet med stort.
 
Eksempler:
    run();
    runFast();
    getBackground();
Yderligere regler:

Variabler

Suns retningslinjer for navngivning

Med undtagelse af variabler, skrives alle forekomster, klasser og klassekonstanter med små og store bogstaver startende med lille. Interne ord begynder med store bogstaver. Variabelnavne bør ikke begynde med understregningstegn _ eller dollartegn $ , selvom det er tilladt.
 
Navne på variabler skal være korte og meningsfulde. Et variabelnavn skal være som et valgbogstav - forstået på den måde, at det hurtigt viser dets formål for læseren. Variabelnavne på ét tegn bør undgås med undtagelse af midlertidige variabler, der efterfølgende kasseres. Almindelige navne på midlertidige variabler er i, j, k, m og n for heltal. c, d og e for tegn.
 
Eksempler:
    int i;
    char c;
    float myWidth;

(Bemærk: Vi følger ikke længere reglen med, at der foran feltnavne med ikke-konstanter skal sættes "f", f.eks. "fDims".)

Konstanter

Suns retningslinjer for navngivning

Navnene på variabelerklærerede klassekonstanter og på ANSI-konstanter skal være med store bogstaver med ord adskilt af understregninger ("_").
 
Eksempler:
    static final int MIN_WIDTH = 4;
    static final int MAX_WIDTH = 999;
    static final int GET_THE_CPU = 1;

Plugins og udvidelsespunkter

Alle plugins herunder de, der indgår i Eclipse-platformen som f.eks. plugins Resources og Workbench, skal have entydige id'er, der følger det samme navngivningsmønster som for Java-pakker. F.eks. får arbejdsbænks-plugins navnet org.eclipse.ui[.*].

Plugin-navneområdet styres hierarkisk. Opret ikke en plugin uden forudgående godkendelse fra ejeren af det omsluttende navneområde

Udvidelsespunkter, der forventer flere udvidelser, skal have navne i flertal. F.eks. "byggeprogrammer" i stedet for "byggeprogram".