Plataforma Eclipse
Convenciones de denominación

Última revisión 4 de junio 2001 - versión 1.0 para org.eclipse

Convenciones de denominación y directrices de la plataforma Eclipse:

Paquetes de Java

La plataforma Eclipse consiste en una colección de paquetes de Java. El espacio del nombre del paquete se rige de acuerdo con las directrices del convenio de denominación de Sun; no deberían crearse subpaquetes sin la aprobación previa del propietario del subárbol del paquete. Los paquetes para la plataforma Eclipse son todos subpaquetes org.eclipse. El primer componente del nombre del paquete tras org.eclipse es denominado el nombre del paquete mayor. Los paquetes mayores siguientes de org.eclipse están asignados al release inicial:
org.eclipse.ant[.*] - Soporte para Ant
org.eclipse.compare[.*] - Soporte para comparación
org.eclipse.core[.*] - Núcleo de la plataforma
org.eclipse.debug[.*] - Depurar
org.eclipse.help[.*] - Soporte de ayuda
org.eclipse.jdi[.*] - Implementación del Interfaz de depuración de Java (JDI) para Eclipse
org.eclipse.jdt[.*] - Herramientas de desarrollo de Java
org.eclipse.jface[.*] - JFace
org.eclipse.pde[.*] - Entorno de desarrollo de Plug-in
org.eclipse.scripting[.*] - Soporte de escritura
org.eclipse.search[.*] - Soporte de búsqueda
org.eclipse.swt[.*] - Kit de utilidades de formato estándar
org.eclipse.ui[.*] - Entorno de trabajo
org.eclipse.update[.*] - Actualización directa de Plug-ins
org.eclipse.vcm[.*] - Gestión de versión y configuración
org.eclipse.webdav[.*] - Soporte para WebDAV
Los siguientes segmentos de nombre de paquete están reservados:
internal - indica un paquete de implementación interna que no contiene ningún API
tests - indica un paquete no API que contiene sólo juegos de tests
examples - indica un paquete no API que contiene únicamente ejemplos
Estos nombres se utilizan como calificadores y sólo deben aparecer después del nombre principal del paquete. Por ejemplo,
org.eclipse.core.internal.resources - Uso correcto
org.eclipse.internal.core.resources - Incorrecto. internal precede al nombre del paquete mayor.
org.eclipse.core.resources.internal - Incorrecto. internal no sigue inmediatamente al nombre del paquete mayor.
Aparte acerca de cómo está estructurada la plataforma Eclipse: La plataforma Eclipse está dividida en núcleo e interfaz de usuario (UI). Cualquier elemento clasificado como núcleo es independiente del sistema de ventanas; las aplicaciones y los plug-ins que dependan del núcleo y no del UI pueden ejecutarse sin responsable. La distinción entre el núcleo y el UI no se corresponde con la distinción entre API y no API; tanto núcleo como UI contienen API. La parte UI de la plataforma Eclipse es conocida como el entorno de trabajo. El entorno de trabajo es una infraestructura de UI de alto nivel para construir productos con interfaces de usuario sofisticados construidos a partir de componentes conectables. El entorno de trabajo está construido sobre JFace, SWT y el núcleo de la plataforma. El SWT (kit de utilidades de formato estándar) es un medio de bajo nivel, independiente del OS de la plataforma, de dirigirse al sistema de ventana nativo. JFace es una infraestructura de UI de nivel medio útil para construir piezas complejas del UI tales como los visores de propiedades. SWT y JFace son interfaces de usuario por definición. Las herramientas de Java constituyen un IDE de Java construido sobre el entorno de trabajo. Final aparte.

Paquetes de API  Los paquetes API son aquellos paquetes que contienen clases e interfaces que deben estar disponibles para los ISV. Los nombres de los paquetes API necesitan tener sentido para el ISV. La cantidad de paquetes diferentes que necesita recordar el ISV debería ser pequeña, dado que una cantidad excesiva de paquetes de API puede dificultar a los ISV el saber qué paquetes necesitan importar. Dentro del paquete de API, todas las clases e interfaces públicas son consideradas API. Los nombres de los paquetes API no deberían contener las expresiones internal, tests, o examples para evitar confusiones con el esquema para la denominación de paquetes no-API.

Internal Implementation Packages  Todos los paquetes que forman parte de la implementación de la plataforma pero que no contienen ningún API que deba exponerse a los ISVs, son considerados paquetes de implementación interna. Todos los paquetes de implementación deberían distinguirse como internos, con la ocurrencia de etiqueta situada justo tras el nombre principal del paquete. A ISVs se le dirá que todos los paquetes marcados como internos están prohibidos. (Una búsqueda simple de texto para ".internal." detecta referencia sospechosa en los archivos fuente; de la misma forma, "/internal/" es sospechosa en los archivos .class).

Paquetes de juegos de tests  Todos los paquetes que contienen juegos de tests deberían llevar el distintivo tests, con la ocurrencia de etiqueta situada justo detrás del nombre del paquete mayor. Los tests totalmente automatizados son la norma ; así, por ejemplo, org.eclipse.core.tests.resources contendrían tests automatizados para el API de org.eclipse.core.resources. Los tests interactivos (aquellos que indudablemente requieren la intervención de una persona) deberán distinguirse con interactivo como el último segmento del nombre del paquete; así, por ejemplo, org.eclipse.core.tests.resources.interactive contendrá los tests interactivos correspondientes.

Paquetes de ejemplos  Todos los paquetes que contienen ejemplos que envían a los ISV deberían distinguirse como ejemplos, con la ocurrencia de etiqueta situadada justo después del nombre del paquete mayor. Por ejemplo, org.eclipse.swt.examples contendría ejemplos de uso del API de SWT.

Reglas adicionales:

Clases e interfaces

Directrices de denominación de Sun
Los nombres de las clase deberían ser sustantivos, en letras variadas con la primera letra de cada palabra interna en mayúsculas. Intente mantener los nombres de sus clases sencillos y descriptivos. Utilice palabras completas - evite los acrónimos y las abreviaturas (a menos que la abreviatura sea mucho más utilizada que el forma completa, como URL o HTML).

Ejemplos:
    class Raster;
    class ImageSprite;

Los nombres de interfaces deberían escribirse en mayúsculas como los nombres de clases.

Para los nombres de interfaces, seguimos la convención "I" para interfaz: todos los nombres de interfaz se encabezan con el prefijo "I". Por ejemplo, "IWorkspace" o "IIndex". Esta convención ayuda a la legibilidad del código haciendo los nombres de interfaz más fácilmente reconocibles. (Las interfaces COM de Microsoft suscriben esta convención).

Reglas adicionales:

Métodos

Directrices de denominación de Sun
Los métodos deberían ser verbos, en letras variadas y con la primera letra escrita en minúscula, con la primera letra de cada palabra interna escrita en mayúsculas.

Ejemplos:
    run();
    runFast();
    getBackground();

Reglas adicionales:

Variables

Directrices de denominación de Sun
Excepto en el caso de las variables, toda instancia, clase y constantes de clase son una mezcla de letras con la primera letra en minúscula. Las palabras internas empiezan con letras mayúsculas. Los nombres de variables no deberían empezar con caracteres subrayados _ o con el signo del dólar $ , a pesar de que ambos están permitidos.

Los nombres de variables deberían ser cortos pero significativos. Al elegir un nombre de variable, éste debería ser mnemotécnico -es decir, diseñado para indicar al observador casual el propósito de su utilización-. Deberían evitarse los nombres de variable de un sólo carácter excepto para variables temporables "desechables". Los nombres comunes para variables temporales son i, j, k, m, y n para números enteros; c, d, y e para caracteres.

Ejemplos:
    int i;
    char c;
    float myWidth;

(Nota: ya no seguimos la convención que antepone nombres de campo no constantes con "f", como "fWidget".)

Constantes

Directrices de denominación de Sun
Los nombres de variables declaradas constantes de clase y de constantes ANSI deberían presentarse en letras mayúsculas con palabras separadas por subrayados ("_").

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

Plug-ins y puntos de extensión

Todos los plug-ins, incluyendo aquellos que forman parte de la plataforma Eclipse, como los plug-ins de recursos y del entorno de trabajo, deben tener identificadores únicos que sigan el mismo modelo de denominación que los paquetes de Java. Por ejemplo, los plug-ins del entorno de trabajo se denominan org.eclipse.ui[.*].

La porción de nombre del plug-in se gestiona de forma jerárquica; no cree un plug-in sin la previa aprobación del propietario de la porción de nombre circundante .

Los puntos de extensión que esperan múltiples extensiones deberían tener nombres plurales. Por ejemplo, "builders" mejor que "builder".