Platforma Eclipse
Konwencje nazewnictwa

Ostatnia modyfikacja: 24 czerwca 2002 (wersja dla projektu Eclipse R2.0)

Konwencje i wytyczne dotyczące nazewnictwa dla platformy Eclipse:

Pakiety Java

Platforma Eclipse składa się z kolekcji pakietów Java. Przestrzeń nazw pakietu musi być zgodna z wytycznymi firmy Sun dotyczącymi nazewnictwa pakietów. Podpakiety nie powinny być tworzone bez zgody właściciela poddrzewa pakietów. Pakiety platformy Eclipse są podpakietami org.eclipse. Pierwszy element nazwy pakietu występujący po elemencie org.eclipse to tzw. główna nazwa pakietu. W środowisku Eclipse 2.0 istnieją następujące główne pakiety org.eclipse:
org.eclipse.ant[.*] - obsługa narzędzia Ant
org.eclipse.compare[.*] - obsługa porównywania
org.eclipse.core[.*] - podstawowy moduł platformy
org.eclipse.debug[.*] - debugowanie
org.eclipse.help[.*] - obsługa systemu pomocy
org.eclipse.jdi[.*] - implementacja interfejsu debugowania Java (JDI) platformy Eclipse
org.eclipse.jdt[.*] - Java Development Tools (JDT)
org.eclipse.jface[.*] - JFace
org.eclipse.pde[.*] - środowisko programowania modułów dodatkowych (PDE)
org.eclipse.search[.*] - obsługa wyszukiwania
org.eclipse.swt[.*] - Standard Widget Toolkit (SWT)
org.eclipse.team[.*] - obsługa zespołu oraz zarządzanie konfiguracją i wersjami
org.eclipse.tomcat[.*] - obsługa serwera Apache Tomcat
org.eclipse.ui[.*] - środowisko robocze
org.eclipse.update[.*] - aktualizowanie/instalowanie
org.eclipse.webdav[.*] - obsługa modułu dodatkowego WebDAV
Następujące segmenty nazw pakietów są zastrzeżone:
internal - oznacza pakiet z implementacją wewnętrzną, który nie zawiera elementów API.
tests - oznacza pakiet bez elementów API, który zawiera tylko pakiety testów.
examples - oznacza pakiet bez elementów API, który zawiera tylko przykłady.
Nazwy te są używane jako kwalifikatory i mogą występować dopiero po głównej nazwie pakietu. Na przykład:
org.eclipse.core.internal.resources - poprawne użycie
org.eclipse.internal.core.resources - niepoprawne użycie (segment internal poprzedza główną nazwę pakietu)
org.eclipse.core.resources.internal - niepoprawne użycie (segment internal nie występuje bezpośrednio po głównej nazwie pakietu)
Uwaga na temat struktury platformy Eclipse: Platforma Eclipse dzieli się na moduł podstawowy (Core) i interfejs użytkownika (UI). Wszystkie elementy należące do modułu podstawowego są niezależne od systemu okienkowego. Aplikacje i moduły dodatkowe, które są zależne od modułu podstawowego, a nie od interfejsu użytkownika, mogą działać bez tego interfejsu. Podział na moduł podstawowy i interfejs użytkownika nie pokrywa się z podziałem na elementy API i elementy inne niż API. Elementy API mogą znajdować się w module podstawowym i interfejsie użytkownika. Interfejs użytkownika platformy Eclipse to tzw. środowisko robocze. Środowisko robocze to struktura interfejsu użytkownika wysokiego poziomu umożliwiająca tworzenie produktów z zaawansowanym interfejsem użytkownika, który jest budowany z dołączanych komponentów. Środowisko robocze jest budowane na podstawie modułu dodatkowego JFace, pakietu SWT i modułu podstawowego. Pakiet SWT (Standard Widget Toolkit) jest to warstwa niskiego poziomu, która jest niezależna od systemu operacyjnego i umożliwia komunikowanie się z rodzimym systemem okienkowym. Moduł dodatkowy JFace jest to struktura interfejsu użytkownika (warstwa średniego poziomu), która jest przydatna przy budowaniu złożonych elementów interfejsu użytkownika (takich jak przeglądarki właściwości). Pakiet SWT i moduł dodatkowy JFace są z definicji komponentami interfejsu użytkownika. Narzędzia Java są środowiskiem IDE Java zbudowanym w oparciu o środowisko robocze. Koniec uwagi.

Pakiety elementów API  Pakiety elementów API są to pakiety zawierające klasy i interfejsy, które muszą być dostępne dla niezależnych producentów oprogramowania. Nazwy pakietów elementów API muszą być dla nich zrozumiałe. Liczba pakietów, które niezależny producent oprogramowania powinien zapamiętać, musi być niewielka, ponieważ przy zbyt dużej liczbie pakietów API trudno zorientować się, które z nich należy zaimportować. Wszystkie klasy i interfejsy public w ramach pakietu elementów API są uważane za elementy API. Nazwy pakietów elementów API nie mogą zawierać segmentu internal, tests ani examples. Dzięki temu nie są one mylone z pakietami elementów innych niż API.

Pakiety implementacji wewnętrznej.  Wszystkie pakiety będące częścią implementacji platformy i niezawierające elementów API, które powinny być udostępniane niezależnym producentom oprogramowania, są uznawane za pakiety implementacji wewnętrznej. Wszystkie pakiety implementacji powinny być oznaczone przy użyciu segmentu internal umieszczonego bezpośrednio po głównej nazwie pakietu. Niezależni producenci oprogramowania będą wiedzieć, że pakiety oznaczone jako internal są dla nich niedostępne. Wystarczy przeprowadzić proste wyszukiwanie tekstowe łańcucha .internal., aby wykryć podejrzane odwołania w plikach źródłowych. W ten sam sposób w plikach .class można wyszukać podejrzany łańcuch /internal/.

Pakiety testów.  Wszystkie pakiety testów powinny być oznaczone przy użyciu segmentu tests umieszczonego bezpośrednio po głównej nazwie pakietu. Standardem są testy w pełni zautomatyzowane. Dlatego na przykład pakiet org.eclipse.core.tests.resources zawierać będzie zautomatyzowane testy elementów API z pakietu org.eclipse.core.resources. Testy interaktywne (wymagające aktywnego udziału osoby testującej) powinny być oznaczone przy użyciu segmentu interactive umieszczonego jako ostatni segment nazwy pakietu. Dlatego na przykład pakiet org.eclipse.core.tests.resources.interactive zawierać będzie odpowiednie testy interaktywne.

Pakiety przykładów.  Wszystkie pakiety zawierające przykłady, które są przekazywane zewnętrznym programistom, powinny być oznaczone przy użyciu segmentu examples umieszczonego bezpośrednio po głównej nazwie pakietu. Na przykład pakiet org.eclipse.swt.examples zawierać będzie przykłady użycia elementów API z pakietu SWT.

Reguły dodatkowe:

Klasy i interfejsy

Wytyczne firmy Sun dotyczące nazewnictwa są następujące:

Nazwy klas powinny być rzeczownikami. Pierwsze litery słów składowych powinny być wielkie, a pozostałe litery powinny być małe. Nazwy klas powinny być proste i zrozumiałe. Należy stosować pełne słowa i unikać skrótów oraz skrótowców, chyba że skrótowiec jest formą częściej spotykaną (np. URL lub HTML).
 
Przykłady:
    class Raster;
    class ImageSprite;
 
Nazwy interfejsów powinny mieć taki sam układ wielkich i małych liter jak nazwy klas.

Nazwy interfejsów należy oznaczać literą I (wszystkie nazwy interfejsów są poprzedzane literą I). Na przykład IWorkspace lub IIndex. Ta konwencja zwiększa czytelność kodu, ułatwiając rozpoznawanie nazw interfejsów. Tej konwencji przestrzegają między innymi interfejsy COM firmy Microsoft.

Reguły dodatkowe:

Metody

Wytyczne firmy Sun dotyczące nazewnictwa są następujące:

Nazwy metod powinny być czasownikami. Pierwsza litera nazwy powinna być mała, a pierwsze litery słów składowych powinny być wielkie.
 
Przykłady:
    run();
    runFast();
    getBackground();
Reguły dodatkowe:

Zmienne

Wytyczne firmy Sun dotyczące nazewnictwa są następujące:

Z wyjątkiem zmiennych, wszystkie nazwy instancji, klas i stałych klas mają różną wielkość liter i zaczynają się od małej litery. Słowa składowe zaczynają się od wielkiej litery. Nazwy zmiennych nie powinny zaczynać się od znaku podkreślenia _ ani znaku dolara $. W innych miejscach używanie tych znaków jest dozwolone.
 
Nazwy zmiennych powinny być krótkie i zrozumiałe. Nazwa zmiennej powinna być na tyle jasna, aby osoba postronna mogła domyśleć się jej przeznaczenia. Należy unikać jednoliterowych nazw zmiennych - można je stosować tylko w przypadku zmiennych tymczasowych. Typowe nazwy zmiennych tymczasowych to i, j, k, m i n w przypadku liczb całkowitych i c, d oraz e dla znaków.
 
Przykłady:
    int i;
    char c;
    float myWidth;

Uwaga: Konwencja nakazująca poprzedzanie nazw pól niebędących stałymi literą f (np. fWidget) już nie obowiązuje.

Stałe

Wytyczne firmy Sun dotyczące nazewnictwa są następujące:

Nazwy zmiennych zadeklarowanych jako stałe klas i stałe ANSI powinny być pisane tylko wielkimi literami, a słowa składowe należy rozdzielać znakiem podkreślenia ("_").
 
Przykłady:
    static final int MIN_WIDTH = 4;
    static final int MAX_WIDTH = 999;
    static final int GET_THE_CPU = 1;

Moduły dodatkowe i punkty rozszerzeń

Wszystkie moduły dodatkowe, w tym także te wchodzące w skład platformy Eclipse (np. Resources i Workbench), muszą mieć unikalne identyfikatory utworzone według takich samych konwencji, co nazwy pakietów Java. Na przykład moduły dodatkowe środowiska roboczego mają nazwy org.eclipse.ui[.*].

Przestrzeń nazw modułów dodatkowych ma strukturę hierarchiczną. Nie można utworzyć modułu bez zgody właściciela nadrzędnej przestrzeni nazw.

Punkty rozszerzeń, w których ma być wiele rozszerzeń, powinny mieć nazwy w liczbie mnogiej. Na przykład builders, a nie builder.