Eclipse-ympäristö
Nimeämiskäytännöt

Muutettu viimeksi 26. toukokuuta 2006

Eclipse-ympäristön nimeämiskäytännöt ja -ohjeet:

Java-paketit

Eclipse-ympäristö sisältää kokoelman Java-paketteja. Paketin nimitilaa ohjataan Sunin pakettien nimeämiskäytäntöjen mukaisesti; alipaketteja ei saisi luoda ilman paketin alirakenteen omistajan lupaa. Kaikki Eclipse-ympäristön paketit ovat org.eclipse-alipaketteja. Ensimmäinen paketin nimen osa osan org.eclipse jälkeen on pääpaketin nimi. Eclipse 2.0 -versioon on määritetty seuraavat org.eclipse-pääpaketit:
org.eclipse.ant[.*] - Ant-tuki
org.eclipse.compare[.*] - Vertailutuki
org.eclipse.core[.*] - Ympäristön ydinosa
org.eclipse.debug[.*] - Vianmääritys
org.eclipse.help[.*] - Ohjetuki
org.eclipse.jdi[.*] - Java-vianmääritysrajapinnan (JDI) Eclipse-toteutus
org.eclipse.jdt[.*] - Java-kehitystyökalut (JDT)
org.eclipse.jface[.*] - JFace
org.eclipse.ltk[.*] - Yleinen kielityökalujen perusrakenne
org.eclipse.osgi[.*] - Eclipse-API vuorovaikutukseen OSGi:n kanssa
org.eclipse.pde[.*] - Lisäosien kehitysympäristö (PDE)
org.eclipse.search[.*] - Hakutuki
org.eclipse.swt[.*] - Widget-vakiotyökalut (SWT)
org.eclipse.team[.*] - Ryhmätuki sekä version ja kokoonpanon hallinta
org.eclipse.text[.*] - Tekstinmuokkausohjelman kehys
org.eclipse.tomcat[.*] - Apache Tomcat -tuki
org.eclipse.ui[.*] - Työympäristö
org.eclipse.update[.*] - Päivitys/asennus
org.eclipse.webdav[.*] - WebDAV-tuki
Seuraavat paketin nimen osat on varattu:
internal - viittaa sisäiseen toteutuspakettiin, joka ei sisällä sovellusohjelmaliittymää
tests - viittaa muuhun kuin sovellusohjelmaliittymäpakettiin, joka sisältää vain testipaketteja
examples - viittaa muuhun kuin sovellusohjelmaliittymäpakettiin, joka sisältää vain esimerkkejä
Näitä nimiä käytetään tarkenteina, ja ne voivat esiintyä vain pääpaketin nimen jälkeen. Esimerkki:
org.eclipse.core.internal.resources - oikein
org.eclipse.internal.core.resources - väärin. Osa internal on ennen pääpaketin nimeä.
org.eclipse.core.resources.internal - väärin. Osa internal ei tule välittömästi pääpaketin nimen jälkeen.

Riippumatta siitä, miten Eclipse-ympäristö on rakennettu, se jaetaan ydinosaan ja käyttöliittymään. Kaikki ydinosaksi luokitellut osat ovat riippumattomia ikkunointijärjestelmästä; niitä sovelluksia ja lisäosia, jotka ovat riippuvaisia ydinosasta eivätkä käyttöliittymästä, voidaan käyttää näyttöpäätteettömässä ympäristössä. Ydinosan ja käyttöliittymän välinen ero ei vastaa sovellusohjelmaliittymän ja muun kuin sovellusohjelmaliittymän välistä eroa; sekä ydinosassa että käyttöliittymässä on sovellusohjelmaliittymä. Eclipse-ympäristön käyttöliittymäosaa kutsutaan työympäristöksi. Työympäristö on ylätason käyttöliittymärakenne, jossa voidaan koontaa lisättävistä osista koostuvia kehittyneitä käyttöliittymiä sisältäviä tuotteita. Työympäristö kootaan JFace-sovelluksen, SWT-sovelluksen ja ympäristön ydinosan päälle. SWT (Widget-vakiotyökalut) on käyttöjärjestelmästä riippumaton alatason sovellus, jonka avulla keskustellaan oman ikkunointijärjestelmän kanssa. JFace on välitason käyttöliittymärakenne, jonka avulla voidaan koota monimutkaisia käyttöliittymän osia, kuten ominaisuuksien katseluohjelmia. SWT ja JFace kuuluvat käyttöliittymään. Java-työvälinejärjestelmä on työympäristön päälle koottu Java IDE.

Sovellusohjelmaliittymäpaketit  Sovellusohjelmaliittymäpaketit sisältävät luokkia ja rajapintoja, joiden on oltava riippumattomien ohjelmistotoimittajien (ISV) käytettävissä. Sovellusohjelmaliittymäpakettien nimien on oltava ymmärrettäviä riippumattomille ohjelmistotoimittajille. Sovellusohjelmaliittymäpaketteja olisi hyvä olla mahdollisimman vähän, sillä muuten riippumattomien ohjelmistotoimittajien on vaikea muistaa, mitkä paketit täytyy tuoda. Sovellusohjelmaliittymäpaketissa kaikkia julkisia luokkia ja rajapintoja pidetään sovellusohjelmaliittymänä. Sovellusohjelmaliittymien nimissä ei saisi olla osia internal, tests tai examples, jotta ne eivät sekoittuisi muihin kuin sovellusohjelmaliittymäpakettien nimiin.

Sisäiset toteutuspaketit  Kaikkia paketteja, jotka ovat osa ympäristön toteutusta mutta joissa ei ole riippumattomien ohjelmistotoimittajien käyttöön toimitettavia sovellusohjelmaliittymiä, pidetään sisäisinä toteutuspaketteina. Kaikki toteutuspaketit olisi merkittävä osalla internal siten, että tunniste tulee heti pääpaketin nimen jälkeen. Riippumattomille ohjelmistotoimittajille kerrotaan, että kaikki osalla internal merkityt paketit eivät ole sallittuja. (Yksinkertainen tekstihaku tekstillä ".internal." havaitsee epäilyttävät viittaukset lähdetiedostoissa; vastaavasti teksti "/internal/" on epäilyttävä .class-tiedostoissa).

Testipaketit  Kaikki testipaketteja sisältävät paketit olisi merkittävä osalla tests siten, että tunniste tulee heti pääpaketin nimen jälkeen. Testit ovat yleensä täysin automaattisia; siten esimerkiksi org.eclipse.core.tests.resources sisältää sovellusohjelmaliittymän automaattiset testit org.eclipse.core.resources-lisäosassa. Vuorovaikutteiset testit (aktiivista testausta vaativat testit) olisi merkittävä siten, että interactive on paketin nimen viimeinen osa; siten esimerkiksi org.eclipse.core.tests.resources.interactive sisältää vastaavat vuorovaikutteiset testit.

Esimerkkipaketit  Kaikki paketit, jotka sisältävät riippumattomille ohjelmistotoimittajille toimitettavia esimerkkejä, olisi merkittävä osalla examples siten, että tunniste tulee heti pääpaketin nimen jälkeen. Esimerkiksi org.eclipse.swt.examples sisältää esimerkkejä, jotka koskevat SWT-sovellusohjelmaliittymän käyttöä.

Lisäsääntöjä:

Luokat ja rajapinnat

Sunin nimeämisohjeiden mukaan

Luokan nimien olisi oltava substantiiveja, joissa käytetään eri kirjainkokoja siten, että kunkin sanan ensimmäinen kirjain on iso. Pyri käyttämään yksinkertaisia ja kuvaavia luokan nimiä. Käytä kokonaisia sanoja - vältä akronyymeja ja lyhenteitä (paitsi jos akronyymi tai lyhenne on selvästi yleisempi kuin pitkä muoto, kuten URL tai HTML).
 
Esimerkkejä:
    class Raster;
    class ImageSprite;
 
Rajapinnan nimet olisi kirjoitettava isolla, kuten luokan nimet.

Rajapinnan nimissä noudatetaan sellaista käytäntöä, että niiden eteen liitetään "I". Esimerkiksi "IWorkspace" tai "IIndex". Tämä käytäntö parantaa koodin luettavuutta, koska rajapinnan nimet on helppo tunnistaa. (Microsoftin COM-rajapinnoissa noudatetaan tätä käytäntöä).

Lisäsääntöjä:

Metodit

Sunin nimeämisohjeiden mukaan

Metodin nimien olisi oltava verbejä, joissa käytetään eri kirjainkokoja siten, että ensimmäinen kirjain on pieni ja kunkin sisäisen sanan ensimmäinen kirjain on iso.
 
Esimerkkejä:
    run();
    runFast();
    getBackground();
Lisäsääntöjä:

Muuttujat

Sunin nimeämisohjeiden mukaan

Muuttujia lukuun ottamatta kaikkien ilmentymien, luokkien ja luokkavakioiden nimissä käytetään eri kirjainkokoja siten, että ensimmäinen kirjain on pieni. Sisäiset sanat alkavat isolla kirjaimella. Muuttujan nimet eivät saisi alkaa alaviivalla _ tai dollarin merkillä $ , vaikka kumpikin sallitaan.
 
Muuttujan nimien olisi oltava lyhyitä mutta ymmärrettäviä. Muuttujan nimen olisi oltava helposti muistettava - siis sellainen, että siitä on helppo päätellä sen käyttötarkoitus. Yhdestä merkistä koostuvia muuttujan nimiä olisi vältettävä muissa kuin "kertakäyttöisissä" tilapäismuuttujissa. Tilapäismuuttujien yleisiä nimiä ovat i, j, k, m ja n kokonaisluvuissa sekä c, d ja e merkeissä.
 
Esimerkkejä:
    int i;
    char c;
    float myWidth;

(Huomautus: Käytäntöä, jonka mukaan muiden kuin vakiokenttien nimien alkuun liitetään "f", esimerkiksi "fWidget" ei enää noudateta.)

Vakiot

Sunin nimeämisohjeiden mukaan

Luokkavakioiksi esiteltyjen muuttujien ja ANSI-muuttujien nimet olisi kirjoitettava isoin kirjaimin siten, että sanojen välillä on alaviiva ("_").
 
Esimerkkejä:
    static final int MIN_WIDTH = 4;
    static final int MAX_WIDTH = 999;
    static final int GET_THE_CPU = 1;

Lisäosat ja laajennuspisteet

Kaikissa lisäosissa, myös niissä, jotka ovat osa Eclipse-ympäristöä, kuten resurssi- ja työympäristölisäosissa, on oltava yksilöllinen tunnus Java-pakettien nimeämismallin mukaisesti. Esimerkiksi työympäristön lisäosien nimet ovat muotoa org.eclipse.ui[.*].

Lisäosan nimitilaa ohjataan hierarkkisesti; älä luo lisäosaa ilman sisällytysnimitilan omistajan lupaa.

Monen laajennuksen laajennuspisteiden nimien olisi oltava monikkomuodossa. Esimerkiksi "builders" eikä "builder".