Modul Eclipse Platform
Pravidla pro pojmenování

Poslední revize 24. června 2002 - verze pro projekt Eclipse R2.0

Pravidla pro pojmenování a směrnice k modulu Eclipse Platform:

Balíčky Java

Modul Eclipse Platform sestává z kolekce javových balíčků. Obor názvů balíčků je spravován v souladu s dokumentem Směrnice společnosti Sun pro pojmenování balíčků; podbalíčky by neměly být vytvářeny bez předchozího schválení od vlastníka podstromu daného balíčku. Balíčky pro platformu Eclipse jsou všechny podbalíčky org.eclipse. První komponenta názvu balíčku po org.eclipse se nazývá hlavní název balíčku. Do platformy Eclipse, verze 2.0, patří následující hlavní balíčky org.eclipse:
org.eclipse.ant[.*] - Podpora pro Ant
org.eclipse.compare[.*] - Podpora porovnávání
org.eclipse.core[.*] - Jádro platformy
org.eclipse.debug[.*] - Ladění
org.eclipse.help[.*] - Podpora nápovědy
org.eclipse.jdi[.*] - Implementace javového rozhraní JDI (Java Debug Interface) pro Eclipse
org.eclipse.jdt[.*] - Nástroje JDT (Java Development Tools) (Java development tools)
org.eclipse.jface[.*] - JFace
org.eclipse.pde[.*] - Vývojové prostředí modulů plug-in PDE (Plug-in Development Environment)
org.eclipse.search[.*] - Podpora vyhledávání
org.eclipse.swt[.*] - Sada nástrojů SWT (Standard Widget Toolkit)
org.eclipse.team[.*] - Týmová podpora včetně správy verzí a konfigurací
org.eclipse.tomcat[.*] - Podpora pro Apache tomcat
org.eclipse.ui[.*] - Workbench pro uživatelské rozhraní
org.eclipse.update[.*] - Aktualizace/instalace
org.eclipse.webdav[.*] - Podpora pro WebDAV
Následující segmenty názvů balíčků jsou rezervovány:
internal - Označuje vnitřní implementaci balíčku, jenž neobsahuje žádné rozhraní API
tests - Označuje balíček bez API, jenž obsahuje pouze testovací sady
examples - Označuje balíček bez API, jenž obsahuje pouze příklady
Tyto názvy slouží jako kvalifikátory a musí se objevit pouze za hlavním názvem balíčku. Například
org.eclipse.core.internal.resources - Správné použití.
org.eclipse.internal.core.resources - Nesprávně. internal je před hlavním názvem balíčku.
org.eclipse.core.resources.internal - Nesprávně. internal není ihned za hlavním názvem balíčku.
Vedlejší poznámka o tom, jak je produkt Eclipse Platform strukturován: je rozdělen na části Core a UI. Cokoli, co se klasifikuje jako Core, je nezávislé na systému oken; aplikace a moduly plug-in, jež závisejí na jádru a nikoli na UI, mohou běžet "bez hlavy". Rozdíl mezi jádrem Core a UI není stejný jako rozdíl mezi API a bez API, protože Core i uživatelské rozhraní UI obsahují API. Část UI modulu Eclipse Platform je také známa pod pojmem modul Workbench. Workbench je rámec vysokoúrovňového UI pro tvorbu produktů s propracovanými uživatelskými rozhraními sestavenými z přídavných komponent. Workbench je postaven na bázi JFace, SWT a jádra platformy. SWT (Standard Widget Toolkit) je nízkoúrovňový a na platformě operačního systému nezávislý prostředek ke komunikaci s nativním systémem oken. JFace je středněúrovňový rámcový systém UI, jenž slouží k vývoji komplexních částí UI, jako jsou prohlížeče vlastností. SWT a JFace jsou definovány jako UI. Java tooling je integrované vývojové prostředí IDE postavené na modulu workbench. Konec vedlejší poznámky.

API Packages  Balíčky rozhraní API obsahují třídy a rozhraní, jež musejí být k dispozici pro nezávislé dodavatele (ISV). Názvy balíčků rozhraní API musejí těmto ISV dávat smysl. Celkový počet různých balíčků, které si ISV musí pamatovat, by měl být malý, protože nadbytek balíčků rozhraní API by mu ztížil orientaci v tom, které balíčky musí importovat. V rámci balíčku rozhraní API jsou všechny veřejné třídy a rozhraní považovány za API. Názvy balíčků rozhraní API by neměly obsahovat internal, tests ani examples, aby nedošlo ke zmatení názvů podle pravidel pro pojmenování balíčku bez API.

Balíčky s vnitřní implementací  Všechny balíčky, jež jsou součástí implementace platformy, ale neobsahují žádné API, které by mělo být odkryto dodavatelům ISV, jsou považovány za balíčky s vnitřní implementací. Všechny balíčky implementace by měly být označeny jako internal a tato značka by měla být zadána ihned za hlavním názvem balíčku. Dodavatelům ISV bude sděleno, že všechny balíčky označené internal jsou pro ně zakázané. (Jednoduché vyhledání textu ".internal." zjistí podezřelý odkaz ve zdrojových souborech a stejně tak "/internal/" je podezřelé v souborech .class).

Test Suite Packages  Všechny balíčky obsahující sady testů by měly být označeny jako tests a tato značka by měla být zadána ihned za hlavním názvem balíčku. Plně zautomatizované testy jsou standardem, takže například org.eclipse.core.tests.resources bude obsahovat zautomatizované testy pro API v org.eclipse.core.resources. Interaktivní testy (ty, jež vyžadují živého testera) by měly být označeny pomocí interactive jako poslední segment názvu balíčku, takže například org.eclipse.core.tests.resources.interactive bude obsahovat odpovídající interaktivní testy.

Examples Packages  Všechny balíčky obsahující příklady určené dodavatelům ISV by měly být označeny jako examples a tato značka by měla být zadána ihned za hlavním názvem balíčku. Například org.eclipse.swt.examples bude obsahovat příklady, jak používat API ze SWT.

Další pravidla:

Třídy a rozhraní

Směrnice společnosti Sun pro pojmenování uvádějí:

Názvy tříd by měla tvořit podstatná jména, přičemž první písmeno každého interního slova by mělo být velké. Zkuste zachovat názvy tříd jednoduché a výstižné. Používejte celá slova - vyhýbejte se akronymům a zkratkám (pokud zkratka není daleko více používaná než její nezkrácený tvar, jako je URL nebo HTML).
 
Příklady:
    class Raster;
    class ImageSprite;
 
Názvy rozhraní by měly mít slova s velkým počátečním písmenem jako názvy tříd.

Co se týče názvů rozhraní, zachováváme konvenci "I" pro interface: všechny názvy rozhraní mají předponu "I". Příklady: "IWorkspace" nebo "IIndex". Tato konvence usnadňuje čitelnost kódu, protože názvy rozhraní jsou snáze rozpoznatelné. (Rozhraní COM společnosti Microsoft zachovávají tuto konvenci).

Další pravidla:

Metody

Směrnice společnosti Sun pro pojmenování uvádějí:

Metody by měly tvořit slovesa, přičemž první písmeno názvu by mělo být malé a první písmeno každého interního slova by mělo být velké.
 
Příklady:
    run();
    runFast();
    getBackground();
Další pravidla:

Proměnné

Směrnice společnosti Sun pro pojmenování uvádějí:

Kromě proměnných mají všechny instance, třídy a třídní konstanty velká i malá písmena a název začínající malým písmenem. Interní slova začínají velkým písmenem. Názvy proměnných by neměly začínat podtržítkem _ ani znakem dolaru $ , ačkoli jsou oba znaky povoleny.
 
Názvy proměnných by měly být krátké a přesto smysluplné. Výběr názvu proměnné by měl zohlednit mnemotechniku - tj. navržen tak, aby běžnému pozorovateli naznačil záměr jejího použití. Jednoznakové názvy proměnných by neměly být používány s výjimkou dočasných proměnných "na jedno použití". Obecné názvy dočasných proměnných jsou i, j, k, m a n pro celá čísla; c, d a e pro znaky.
 
Příklady:
    int i;
    char c;
    float myWidth;

(Poznámka: nyní se již neřídíme konvencí, která dává před názvy nekonstantních polí předponu "f", jako je "fWidget".)

Konstanty

Směrnice společnosti Sun pro pojmenování uvádějí:

Názvy proměnných (deklarovaných jako konstanty třídy) a konstant ANSI by měly tvořit pouze velká písmena a slova by měla oddělovat podtržítka ("_").
 
Příklady:
    static final int MIN_WIDTH = 4;
    static final int MAX_WIDTH = 999;
    static final int GET_THE_CPU = 1;

Moduly plug-in a body rozšíření

Všechny moduly plug-in včetně těch, jež jsou částí platformy Eclipse (jako jsou moduly plug-in Resources a Workbench), musejí mít jedinečné identifikátory se stejným vzorem pojmenování jako balíčky Java. Například moduly plug-in pro workbench jsou pojmenovány org.eclipse.ui[.*].

Obor názvů modulů plug-in je spravován hierarchicky; nevytvářejte název modulu plug-in bez předchozího schválení od vlastníka zapouzdřujícího oboru názvů.

Body rozšíření, jež očekávají více rozšíření, by měly mít názvy v množném čísle. Například "builders" spíše než "builder".