diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab90dec2..72131ba0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -193,7 +193,10 @@ Contributors: Язык ведения проекта (issue, аудит и т.д.) - Русский, т.к. ориентация на русское сообщество программистов. Поддержка разработчиков на других языка в будущем может быть решена дополнительно. -Все интерфейсные тексты должны быть написаны на английском яызке и локализированы - вынесены в отдельные ресурсные файлы `*.properties`. +Все интерфейсные тексты, которые видит пользователь, должны быть написаны на английском яызке и локализированы - вынесены в отдельные ресурсные файлы `*.properties`. + +Кодировка файлов `*.properties` - UTF-8. + Все локализируемые ресурсные файлы должны быть переведены на дополнительный русский язык. Например: @@ -201,8 +204,34 @@ Contributors: - `messages.properties` - основной интерфейс, должен содержать английский интерфейс - `messages_ru.properties` - дополнительный интерфейс на русском языке +В проекте используется система локализации **Eclipse NLS**: -Для большего удобства используйте помощник Eclipse Externalize Strings Wizard, который помогает переносить интерфейсные строки в ресурсные файлы. +- Необходимо создавать final-класс наследник `org.eclipse.osgi.util.NLS` +- В классе указывается консанта `BUNDLE_NAME` с полным квалификтором файла `messages` в котором хранятся локализованные сообщения. +- Создаются публичные константы, которые являются ключами в ресурсных файлах + +```java +final class Messages + extends NLS +{ + private static final String BUNDLE_NAME = "com.e1c.v8codestyle.md.check.messages"; //$NON-NLS-1$ + public static String CommonModuleNameClient_description; + public static String CommonModuleNameClient_message; + static + { + // initialize resource bundle + NLS.initializeMessages(BUNDLE_NAME, Messages.class); + } + + private Messages() + { + } +} +``` + +Для большего удобства используйте помощник Eclipse Externalize Strings Wizard, который помогает переносить интерфейсные строки из кода в ресурсные файлы, с автоматическим созданием файла констант NLS. + +Для редактирования ресурсных файлов следует использовать плагин из Маркет-плайса Eclipse: [ResourceBundle Editor](https://marketplace.eclipse.org/node/2628188) или аналогичны, позволяющий синхронно редактировать интерфейсы на нескольких языках, корректно учитывающий кодировку UTF-8. ### Code Style diff --git a/Check_Convention.md b/Check_Convention.md index 8ad7585b..ad1bd421 100644 --- a/Check_Convention.md +++ b/Check_Convention.md @@ -64,7 +64,7 @@ method-never-used #### Слова-паразиты -Следует избегать использования "слов-паразитов" которые не добавляют никакого смысла в код проверки, например слова: check, error, warning, артикли a, the, to, is, are и т.д. problem, valid +Следует избегать использования "слов-паразитов", которые не добавляют никакого смысла в код проверки, например слова: check, error, warning, артикли a, the, to, is, are и т.д. problem, valid НЕПРАВИЛЬНО @@ -106,13 +106,15 @@ function-has-no-return-type - Что проверяем, какую ошибку находит - Существительное, в именительном падеже +- Наименование должно быть локализовано через NLS класс ### Детальное описание 1. Следует указывать описание при регистрации проверки в классе. +2. Детальное описание должно быть локализовано через NLS класс 2. Формируется описание в виде `check.descriptions/check-id.md` и `check.descriptions/ru/check-id.md` с детальным описанием -3. Ссылку на стандарт следует указывать в секции "См." +3. Ссылку на стандарт, по которому выполняется проверка, следует указывать в секции `## См.` (или `## See`) в файлах описаний `check-id.md` 4. Следует описывать все возможные варианты `НЕПРАВИЛЬНО` и `ПРАВИЛЬНО` которые находит проверка. Желательно использовать примеры из тестов. ### Тип (issueType) @@ -152,7 +154,7 @@ function-has-no-return-type - Возможность внести исключения в правило поиска проблемных мест - Нет смысла в параметрах если проверяется единственный объект и какое-либо исключение равно отключению проверки - Используйте паттерны в параметрах для поиска исключений -- Любые значения (текстовые, числовые, с большой вариабельностью, кроме Булево) следует задавать через параметры +- Любые константные значения (текстовые, числовые, с большой вариабельностью, Булево), которое имеют отношение к логике проверки, следует задавать через параметры Типовые примеры: - Исключение по имени метаданного @@ -162,6 +164,15 @@ function-has-no-return-type 1. имена параметров должны быть понятны в контексте проверки 2. имена параметров пишутся в `CamelCase`, с маленькой буквы 3. Константа с именем параметра должна быть публичной +4. Заголовок параметра должен быть локализован через NLS класс + + +### Компоненты расширяющие функциональность + +- Проверки, проверяющие 1 объект на наличие ошибок, в общем случае следует наследовать от `com._1c.g5.v8.dt.check.components.BasicCheck` или аналогичных для специфичных областей `com.e1c.g5.v8.dt.bsl.check.DocumentationCommentBasicDelegateCheck`, `com.e1c.g5.v8.dt.ql.check.QlBasicDelegateCheck` +- При наличии нескольих повторяющихся фрагментов кода c параметризацией и фильтрацией объектов - желательно создавать компонент `com._1c.g5.v8.dt.check.components.IBasicCheckExtension` для переиспользования. +- При необходимости использовать существующие компоненты `com._1c.g5.v8.dt.check.components.ModuleTopObjectNameFilterExtension`, `com._1c.g5.v8.dt.check.components.TopObjectFilterExtension` + ## Логика проверки / код проверки @@ -174,7 +185,8 @@ function-has-no-return-type 1. В чем ошибка 2. Формат текста: существительное, именительный падеж -2. Указание значений параметров в сообщении +3. Указание значений параметров в сообщении +4. Сообщение должно быть локализовано через NLS класс Примеры: 1. Переменная не была инициализирована