Plataforma Eclipse
Convenios de denominación

Última revisión el 24 de junio de 2002 - versión del proyecto Eclipse R2.0

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

Paquetes Java

La plataforma Eclipse consta de una colección de paquetes Java. El espacio de nombres de paquete está gestionado en conformidad con las directrices del convenio de denominación de Sun; no deben crearse subpaquetes sin la aprobación previa del propietario del subárbol de paquetes. Todos los paquetes de la plataforma Eclipse son subpaquetes de org.eclipse. El primer componente del nombre del paquete tras org.eclipse se llama nombre de paquete principal. En el release Eclipse 2.0, están asignados los siguientes paquetes principales de org.eclipse:
org.eclipse.ant[.*] - Soporte de Ant
org.eclipse.compare[.*] - Soporte de comparación
org.eclipse.core[.*] - Núcleo de la plataforma
org.eclipse.debug[.*] - Depuración
org.eclipse.help[.*] - Soporte de ayuda
org.eclipse.jdi[.*] - Implementación de la interfaz de depuración Java (JDI) para Eclipse
org.eclipse.jdt[.*] - Herramientas de desarrollo Java
org.eclipse.jface[.*] - JFace
org.eclipse.pde[.*] - Entorno de desarrollo de conectores
org.eclipse.search[.*] - Soporte de búsqueda
org.eclipse.swt[.*] - Juego de herramientas de widgets estándar (SWT)
org.eclipse.team[.*] - Soporte de equipo y gestión de versiones y configuraciones
org.eclipse.tomcat[.*] - Soporte de Apache tomcat
org.eclipse.ui[.*] - Entorno de trabajo
org.eclipse.update[.*] - Actualización/instalación
org.eclipse.webdav[.*] - Soporte de WebDAV
Los siguientes segmentos de nombre de paquete están reservados:
internal: indica un paquete de implementación interna que no contiene ninguna API
tests: indica un paquete no de API que solo contiene suites de prueba
examples: indica un paquete no de API que contiene únicamente ejemplos
Estos nombres se utilizan como calificadores y solo 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 de paquete principal.
org.eclipse.core.resources.internal - Incorrecto. internal no sigue inmediatamente al nombre de paquete principal.
Dejando de lado cómo está estructurada, 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 conectores que dependan del núcleo y no de la UI pueden ejecutarse sin responsable. La distinción entre el núcleo y la UI no se corresponde con la distinción entre API y no API; tanto el núcleo como la UI contienen API. La parte UI de la plataforma Eclipse se conoce como entorno de trabajo. El entorno de trabajo es una infraestructura de UI de alto nivel que permite construir productos con interfaces de usuario (UI) sofisticadas construidas a partir de componentes conectables. El entorno de trabajo está construido sobre JFace, SWT y el núcleo de la plataforma. SWT (juego de herramientas de widgets estándar) es un medio de bajo nivel (independiente de la plataforma del SO) de comunicarse con el sistema de ventanas nativo. JFace es una infraestructura de UI de nivel medio útil para construir piezas complejas de la UI tales como los visores de propiedades. SWT y JFace son interfaces de usuario por definición. Las herramientas Java constituyen un IDE Java construido sobre el entorno de trabajo. Final aparte.

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

Paquetes de implementación interna  Todos los paquetes que forman parte de la implementación de la plataforma, pero que no contienen ninguna API que deba exponerse a los ISV, se consideran paquetes de implementación interna. Todos los paquetes de implementación deben marcarse con el código internal, que debe aparecer justo después del nombre principal del paquete. A los ISV se les dirá que todos los paquetes marcados como internal están reservados. (Una búsqueda simple de texto de ".internal." detecta una referencia sospechosa en los archivos fuente; de la misma forma, "/internal/" es sospechosa en los archivos .class).

Paquetes de suites de prueba  Todos los paquetes que contienen suites de prueba deben marcarse con el código tests, que debe figurar justo después del nombre principal del paquete. Las pruebas totalmente automatizadas son la norma; así, por ejemplo, el paquete org.eclipse.core.tests.resources contendría pruebas automatizadas para la API de org.eclipse.core.resources. Las pruebas interactivas (las que indudablemente requieren la intervención de una persona) deben marcarse con el código interactive como el último segmento del nombre del paquete; así, por ejemplo, org.eclipse.core.tests.resources.interactive contendrá las pruebas interactivas correspondientes.

Paquetes de ejemplos  Todos los paquetes que contienen ejemplos que se envían a los ISV deben marcarse con el código examples, que debe aparecer justo después del nombre principal del paquete. Por ejemplo, el paquete org.eclipse.swt.examples contendría ejemplos de cómo utilizar la API de SWT.

Reglas adicionales:

Clases e interfaces

Directrices de denominación de Sun
Los nombres de las clases deben ser sustantivos, combinando las mayúsculas/minúsculas de tal manera que la primera letra de cada palabra interna esté escrita con mayúscula. 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 se utilice mucho más que el formato completo, como en URL o HTML).

Ejemplos:
    class Raster;
    class ImageSprite;

Los nombres de las interfaces deben escribirse con mayúscula como los de las clases.

Para los nombres de las interfaces, seguimos el convenio de escribir una "I" por interfaz: todos los nombres de interfaz empiezan por una "I". Por ejemplo, "IWorkspace" o "IIndex". Este convenio sirve de ayuda para la legibilidad del código, haciendo que los nombres de las interfaces se reconozcan fácilmente. (Las interfaces COM de Microsoft suscriben este convenio).

Reglas adicionales:

Métodos

Directrices de denominación de Sun
Los métodos deben ser verbos, combinando las mayúsculas/minúsculas de tal manera que la primera letra esté escrita con minúscula, y la primera letra de cada palabra interna esté escrita con mayúscula.

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

Reglas adicionales:

Variables

Directrices de denominación de Sun
Excepto en el caso de las variables, toda instancia, clase y constante de clase se escriben combinando las mayúsculas/minúsculas de tal manera que la primera letra es una minúscula. Las palabras internas empiezan con una letra mayúscula. Los nombres de las variables no deben empezar por los caracteres de subrayado _ o de signo del dólar $, a pesar de que ambos están permitidos.

Los nombres de las variables deben ser cortos pero significativos. La elección del nombre de una variable debe ser nemotécnica, es decir, diseñada para indicar al observador casual el propósito de su utilización. Deben evitarse los nombres de variable de un solo carácter, excepto para las variables temporales "desechables". Los nombres comunes de las 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 el convenio que prefija los nombres de campo no constantes con "f", como en "fWidget").

Constantes

Directrices de denominación de Sun
Los nombres de las variables declaradas como constantes de clase y constantes de ANSI deben escribirse todo con mayúscula, y las palabras separadas por caracteres de subrayado ("_").

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

Conectores y puntos de extensión

Todos los conectores, incluidos los que forman parte de la plataforma Eclipse, como los conectores de recursos y del entorno de trabajo, deben tener identificadores exclusivos que sigan el mismo patrón de denominación que los paquetes Java. Por ejemplo, los conectores del entorno de trabajo se denominan org.eclipse.ui[.*].

El espacio de nombres del conector se gestiona de forma jerárquica; no cree un conector sin la previa aprobación del propietario del espacio de nombres delimitador.

Los puntos de extensión que esperan múltiples extensiones deben tener nombres en plural. Por ejemplo, "builders", en vez de "builder".

Copyright IBM Corporation y otros 2000, 2003.