Платформа Eclipse
Соглашения об именах

Последнее исправление: 24 июня 2002 г. - версия для проекта Eclipse R2.0

Соглашения и рекомендации об именах для платформы Eclipse:

Пакеты Java

Платформа Eclipse представляет собой набор пакетов Java. Пространство имен пакетов управляется в соответствии с рекомендациями по присвоению имен компании Sun; дочерние пакеты следует создать только после получения подтверждения от владельца соответствующего поддерева пакетов. Все пакеты, поддерживаемые платформой Eclipse, представляют собой дочерние пакеты org.eclipse. Первый фрагмент имени пакета после org.eclipse называется основным именем пакета. В Eclipse 2.0 предусмотрены следующие основные пакеты org.eclipse:
org.eclipse.ant[.*] - Поддержка Ant
org.eclipse.compare[.*] - Поддержка сравнения
org.eclipse.core[.*] - Ядро платформы
org.eclipse.debug[.*] - Отладка
org.eclipse.help[.*] - Поддержка справки
org.eclipse.jdi[.*] - Реализация интерфейса отладки Java (JDI) для Eclipse
org.eclipse.jdt[.*] - Инструменты разработки Java
org.eclipse.jface[.*] - JFace
org.eclipse.pde[.*] - Среда разработки модулей
org.eclipse.search[.*] - Поддержка поиска
org.eclipse.swt[.*] - Standard Widget Toolkit
org.eclipse.team[.*] - Коллективная работа, управление версиями и конфигурациями
org.eclipse.tomcat[.*] - Поддержка Apache Tomcat
org.eclipse.ui[.*] - Рабочая среда
org.eclipse.update[.*] - Обновление/установка
org.eclipse.webdav[.*] - Поддержка WebDAV
Ниже перечислены зарезервированные фрагменты имен пакетов:
internal - указывает на пакет внутренней реализации, в состав которого не входит API
tests - указывает на пакет, не содержащий API, в состав которого входят только комплекты тестов
examples - указывает на пакет, не содержащий API, в состав которого входят только примеры
Они выполняют роль спецификаторов и допустимы только после основного имени пакета. Например:
org.eclipse.core.internal.resources - Правильно
org.eclipse.internal.core.resources - Неправильно. internal предшествует основному имени пакета.
org.eclipse.core.resources.internal - Неправильно. internal следует не сразу за основным именем пакета.
Отвлечемся на некоторое время от рассмотрения структуры платформы Eclipse: Платформа Eclipse разделена на ядро и пользовательский интерфейс. Все компоненты, относящиеся к ядру, не зависят от системы организации окон; приложения и модули ядра, не использующие функции пользовательского интерфейса, могут работать в автономном режиме. Различие между ядром и пользовательским интерфейсом нельзя рассматривать как различие между компонентами, связанными и не связанными с API, поскольку API входят в состав как ядра, так и пользовательского интерфейса. Компонент платформы Eclipse, описывающий пользовательский интерфейс, называется рабочей средой. Рабочая среда представляет собой среду пользовательского интерфейса высокого уровня, на основе которой можно из отдельных компонентов можно создавать продукты со сложным пользовательским интерфейсом. Рабочая среда создается поверх JFace, SWT и ядра платформы. SWT (Standard Widget Toolkit) - это средство взаимодействия с исходной системой организации окон низкого уровня, независящее от операционной системы. JFace представляет собой среду пользовательского интерфейса промежуточного уровня, предназначенную для создания сложных компонентов пользовательского интерфейса, таких как программы просмотра свойств. SWT и JFace по определению относятся к пользовательскому интерфейсу. Инструменты Java - это интегрированная среда разработки Java, устанавливаемая поверх рабочей среды. Вернемся к рассмотрению структуры платформы.

Пакеты API Пакеты API содержат классы и элементы, предоставляемые независимым вендорам программного обеспечения. Имена пакетов API должны быть значимыми для вендоров. Рекомендуется создавать минимальное число пакетов, поскольку импорт слишком большого числа пакетов API может вызвать у вендора затруднения. Все общедоступные классы и интерфейсы, входящие в состав таких пакетов, относятся к API. Для того чтобы избежать путаницы с пакетами, не связанными с API, в именах пакетов API не следует указывать значения internal, tests и examples.

Пакеты внутренней реализации Все пакеты, относящиеся к реализации платформы, но не содержащие API, следует предоставлять независимым вендорам программного обеспечения в качестве пакетов внутренней реализации. Во всех пакетах реализации следует указывать ключевое слово internal вместе с тегом после основного имени пакета. Все пакеты, содержащие ключевое слово internal, независимы. (Простой текстовый поиск строки ".internal." позволяет найти в файлах исходного кода подозрительные ссылки; например, строка "/internal/" не должна встречаться в файлах .class).

Пакеты комплектов тестов Все пакеты, содержащие комплекты тестов, следует обозначать с помощью ключевого слова tests с тегом после основного имени пакета. Как правило, тесты работают в автоматическом режиме. Таким образом, пакет org.eclipse.core.tests.resources содержит тесты для API из org.eclipse.core.resources. Интерактивные тесты (требующие вмешательства пользователя) следует обозначать ключевым словом interactive в последнем фрагменте имени пакета. Например, org.eclipse.core.tests.resources.interactive содержит соответствующие интерактивные тесты.

Пакеты примеров Все пакеты, содержащие примеры, следует обозначать с помощью ключевого слова examples с тегом после основного имени пакета. Например, org.eclipse.swt.examples содержит примеры работы с API SWT.

Дополнительные правила:

Классы и интерфейсы

В рекомендациях по присвоению имен компании Sun указано следующее:

В качестве имен классов следует использовать существительные из символов различного регистра. Первая буква каждого составного слова должна быть прописной. Указывайте простые и описательные имена классов. Используйте целые слова, избегайте аббревиатур и сокращений (кроме тех случаев, когда аббревиатуры более распространены, чем полное название, например, URL или HTML).
 
Примеры:
    class Raster;
    class ImageSprite;
 
В именах интерфейсов прописные буквы используются как в именах классов.

Соглашение об именах элементов предусматривает применение в именах интерфейсов префикса "I". Например, IWorkspace" или "IIndex". Такой подход позволяет улучшить читаемость исходного кода, поскольку интерфейсы можно легко распознать. (Этому соглашению соответствуют интерфейсы Microsoft COM).

Дополнительные правила:

Методы

В рекомендациях по присвоению имен компании Sun указано следующее:

В качестве имен методов следует использовать глаголы из символов различного регистра. Первый символ имени должен быть строчным, а все последующие составные слова должны начинаться с прописной буквы.
 
Примеры:
    run();
    runFast();
    getBackground();
Дополнительные правила:

Переменные

В рекомендациях по присвоению имен компании Sun указано следующее:

За исключением переменных, имена всех экземпляров, классов и констант классов должны начинаться со строчной буквы, за которой допустимы символы различной регистра. Составные слова должны начинаться с прописных букв. Имена переменных не должны начинаться с подчеркивания _ или символа доллара $, хотя применение этих символов разрешено.
 
Имена переменных должны быть краткими и вместе с тем значимыми. Имя переменной следует выбирать таким образом, чтобы ее предназначение было понятно стороннему наблюдателю. Не рекомендуется указывать имена, состоящие из одного символа. Это допустимо только для промежуточных переменных. Общепринятые имена временных переменных для целых чисел - i, j, k, m и n; для символов - c, d и e.
 
Примеры:
    int i;
    char c;
    float myWidth;

(Примечание: соглашение, предусматривающее применение префикса "f" для имен непостоянных полей (например, "fWidget", больше не используется.)

Константы

В рекомендациях по присвоению имен компании Sun указано следующее:

Имена переменных, объявленных константами классов, а также имена констант ANSI должны состоять из прописных букв. В качестве разделителя составных слов применяется символ подчеркивания ("_").
 
Примеры:
    static final int MIN_WIDTH = 4;
    static final int MAX_WIDTH = 999;
    static final int GET_THE_CPU = 1;

Модули и точки расширения

Все модули, в том числе, входящие в состав платформы Eclipse (модули ресурсов и рабочей среды), должны иметь уникальные идентификаторы с именам, соответствующими соглашению об именах, принятому для пакетов Java. Например, модули рабочей среды называются org.eclipse.ui[.*].

Для пространства имен модуля характерно иерархическое управление. Поэтому не рекомендуется создавать модули без разрешения владельца используемого пространства имен.

Точки расширения, предполагающие настройку нескольких расширений, должны иметь имена, указанные в множественном числе. Например, builders", а не "builder".