Piattaforma Eclipse
Convenzioni di denominazione

Versione del progetto Eclipse R2.0 - Ultima revisione 24 giugno 2002

Convenzioni di denominazione e linee guida per la piattaforma Eclipse:

Pacchetti Java

La piattaforma Eclipse consiste in un insieme di pacchetti Java. Lo spazio dei nomi del pacchetto è gestito in conformità con le istruzioni sulla denominazione dei pacchetti Sun; non è possibile creare pacchetti secondari senza aver prima ottenuto l'approvazione dal proprietario della struttura secondaria del pacchetto. I pacchetti per la piattaforma Eclipse sono tutti pacchetti secondari org.eclipse. Il primo nome di pacchetto successivo org.eclipse è denominato pacchetto principale. I successivi pacchetti principali di org.eclipse sono assegnati nella versione 2.0 di Eclipse:
org.eclipse.ant[.*] - Supporto Ant
org.eclipse.compare[.*] - Supporto confronto
org.eclipse.core[.*] - Platform core
org.eclipse.debug[.*] - Debug
org.eclipse.help[.*] - Supporto guida
org.eclipse.jdi[.*] - Implementazione Eclipse di JDI (Java Debug Interface)
org.eclipse.jdt[.*] - Java development tools
org.eclipse.jface[.*] - JFace
org.eclipse.pde[.*] - Ambiente di sviluppo del plug-in
org.eclipse.search[.*] - Supporto per la ricerca
org.eclipse.swt[.*] - Standard Widget Toolkit
org.eclipse.team[.*] - Supporto team, versione e gestione della configurazione
org.eclipse.tomcat[.*] - Supporto Apache tomcat
org.eclipse.ui[.*] - Workbench
org.eclipse.update[.*] - Aggiornamento/installazione
org.eclipse.webdav[.*] - Supporto WebDAV
I segmenti di nomi di pacchetto sono riservati:
internal - indica un pacchetto di implementazione interna che contiene elementi non API
tests - indica un pacchetto non API che contiene solo istanze di verifica
examples - indica un pacchetto non API che contiene solo esempi
I nomi che seguono vengono utilizzati come qualificatori e devono essere visualizzati solo dopo il nome del pacchetto principale. Ad esempio,
org.eclipse.core.internal.resources - Uso corretto.
org.eclipse.internal.core.resources - Uso non corretto: internal precede il nome del pacchetto principale.
org.eclipse.core.resources.internal - Uso non corretto: internal non viene riportato immediatamente dopo il nome del progetto principale.
A parte il modo in cui è strutturata la piattaforma Eclipse, essa è suddivisa in Core e UI. Tutto ciò che è classificato come Core è indipendente dal sistema Windows; le applicazioni e i plug-in che dipendono da Core e non anche da UI possono essere eseguiti indipendentemente. La distinzione tra Core e UI non rispecchia la distinzione tra API e non API: sia Core che UI contengono API. La partizione UI della piattaforma Eclipse è denominata workbench. Il workbench è una struttura UI di alto livello, per la creazione di prodotti tramite sofisticate interfacce derivate da componenti collegabili. Il workbench è costruito su JFace, SWT e Platform Core. SWT (Standard Widget Toolkit) è uno strumento di basso livello, su piattaforma indipendente dal sistema operativo, per la comunicazione con il sistema Windows nativo. JFace è una struttura di interfaccia di medio livello che consente di creare segmenti complessi di interfaccia come i visualizzatori di proprietà. SWT e JFace sono interfacce utente per definizione. La strumentazione Java è un IDE Java costruito sul workbench .

Pacchetti API.  I pacchetti API contengono classi e interfacce che devono essere disponibili per gli ISV. I nomi dei pacchetti API devono essere comprensibili per gli ISV. Il numero dei diversi pacchetti che gli ISV devono elaborare non deve essere troppo elevato, altrimenti potrebbe risultare troppo difficile l'identificazione dei pacchetti da importare. In un pacchetto API, tutte le classi e le interfacce pubbliche sono considerate API. I nomi dei pacchetti API non devono contenere internal, tests o examples per evitare confusione con gli schemi di denominazione dei pacchetti non API.

Pacchetti di implementazione interna.  Tali vengono considerati tutti i pacchetti che concorrono all'implementazione della piattaforma, ma non contengono elementi API da esporre agli ISV. Tutti i pacchetti di implementazione dovrebbero essere indicati come internal, con il tag posto immediatamente dopo il nome del pacchetto principale. Agli ISV verrà indicato che tutti i pacchetti contrassegnati internal non devono essere considerati. Una semplice ricerca del testo ".internal." rileva un riferimento nei file di origine, così come "/internal/" viene rilevato nei file .class.

Pacchetti per la suite di verifica.  Tutti i pacchetti che contengono le suite di verifica dovrebbero essere indicati come tests, con il tag posto immediatamente dopo il nome del pacchetto principale. Di norma, sono previste verifiche completamente automatizzate; così, ad esempio, org.eclipse.core.tests.resources contiene verifiche automatiche per API in org.eclipse.core.resources. Le verifiche interattive (quelle che richiedono l'intervento dell'utente) dovrebbero essere indicate con interactive come ultimo segmento nel nome del pacchetto; così, ad esempio, org.eclipse.core.tests.resources.interactive conterrà le relative verifiche interattive.

Pacchetti di esempio.  Tutti i pacchetti che contengono esempi relativi agli ISV dovrebbero essere indicati come examples, con il tag posto immediatamente dopo il nome del pacchetto principale. Ad esempio, org.eclipse.swt.examples conterrà gli esempi sull'utilizzo dell'API SWT.

Ulteriori regole:

Classi e interfacce

Le istruzioni sulla denominazione Sun prevedono che:
I nomi delle classi devono essere sostantivi e la prima lettera di ciascuna parola interna deve essere maiuscola. Occorre utilizzare nomi di classi semplici e descrittivi. Utilizzare parole intere ed evitare gli acronimi e le abbreviazioni, a meno che l'abbreviazione non risulti più chiara della forma estesa, come nei caso di URL e HTML.

Esempi:
    class Raster;
    class ImageSprite;

Le interfacce devono utilizzare la maiuscola in maniera analoga ai nomi delle classi.

Per nomi di interfaccia, viene utilizzata la "I" a indicare l'interfaccia; così, ogni nome di interfaccia ha come prefisso una "I". Ad esempio, "IWorkspace" o "IIndex". Questa convenzione semplifica la leggibilità del codice rendendo più facilmente riconoscibili i nomi di interfaccia. Le interfacce COM di Microsoft aderiscono a questa convenzione.

Ulteriori regole:

Metodi

Le istruzioni sulla denominazione Sun prevedono che:
I nomi dei metodi devono essere verbi con la prima lettera minuscola e la prima lettera di ciascuna parola interna maiuscola.

Esempi:
    run();
    runFast();
    getBackground();

Ulteriori regole:

Variabili

Le istruzioni sulla denominazione Sun prevedono che:
Eccetto le variabili, tutte le istanze, le classi e le costanti di classe utilizzano caratteri misti con la prima lettera minuscola. Le parole interne iniziano con lettera maiuscola. I nomi di variabili non devono iniziare con la sottolineatura _ o con il simbolo del dollaro $, sebbene entrambi i caratteri siano supportati.

I nomi di variabile devono essere significativi. Il nome della variabile deve essere facile da ricordare, dal momento che deve essere in grado di indicare la propria funzione a un osservatore casuale. È consigliabile evitare nomi di variabili di un solo carattere, salvo i casi di soluzioni temporanee. I nomi comuni per le variabili temporanee sono i, j, k, m e n per i numeri interi e c, d e e per i caratteri.

Esempi:
    int i;
    char c;
    float myWidth;

Nota: non viene più adottata la convenzione di utilizzare "f" come prefisso dei nomi dei campi non costanti, come nel caso di "fWidget".

Costanti

Le istruzioni sulla denominazione Sun prevedono che:
I nomi delle variabili dichiarate costanti di classe e delle costanti ANSI devono essere maiuscole con le parole separate dalle sottolineature ("_").

Esempi:
    static final int MIN_WIDTH = 4;
    static final int MAX_WIDTH = 999;
    static final int GET_THE_CPU = 1;

Plug-in e punti di estensione

Tutti i plug-in, compresi quelli che fanno parte della piattaforma Eclipse, come i plug-in delle risorse e del workbench, devono avere un identificativo univoco seguito dallo stesso modello di denominazione dei pacchetti Java. Ad esempio, i plug-in del workbench vengono denominati org.eclipse.ui[.*].

Lo spazio dei nomi del plug-in viene gestito gerarchicamente; non creare plug-in senza l'approvazione del proprietario dello spazio dei nomi di inclusione.

I punti di estensione che prevedono estensioni multiple devono avere nomi plurali. Ad esempio, "builders" piuttosto che "builder".

Copyright IBM Corporation e altri 2000, 2003.