diff --git a/docs/README.md b/docs/README.md index 75d28b40..d67beb5b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,14 +5,14 @@ ## Основные возможности - [Проверки кода и метаданных](checks/readme.md) по [стандартам 1С](https://its.1c.ru/db/v8std) - - [Проверки метаданных](checks/md.md) - - [Проверки Форм](checks/form.md) - - [Проверки прав ролей](checks/right.md) - - [Проверки модулей](checks/bsl.md) - - [Проверки языка запросов](checks/ql.md) + - [Проверки метаданных](checks/md.md) + - [Проверки Форм](checks/form.md) + - [Проверки прав ролей](checks/right.md) + - [Проверки модулей](checks/bsl.md) + - [Проверки языка запросов](checks/ql.md) - Дополнительные инструменты, улучшающие и ускоряющие работу по стандартам 1С - - [Авто-сортировка метаданных](tools/autosort.md) - - [Создание общих модулей по типам](tools/common-module-types.md) + - [Авто-сортировка метаданных](tools/autosort.md) + - [Создание общих модулей по типам](tools/common-module-types.md) ## Участие в проекте diff --git a/docs/checks/acc_index.md b/docs/checks/acc_index.md index 09300a3e..e4ead31c 100644 --- a/docs/checks/acc_index.md +++ b/docs/checks/acc_index.md @@ -67,6 +67,7 @@ Присоединяйтесь к проекту [https://github.com/1C-Company/v8-code-style](https://github.com/1C-Company/v8-code-style)! Будем благодарны Вам за помощь! Можно помочь: + - улучшить документации по проверкам и инструментам см. [задачи](https://github.com/1C-Company/v8-code-style/labels/documentation), см. [правила](https://github.com/1C-Company/v8-code-style/blob/master/docs/contributing/documentation.md) - написать проверку на Java см. [задачи для новичка](https://github.com/1C-Company/v8-code-style/labels/good%20first%20issue), см. [правила](https://github.com/1C-Company/v8-code-style/blob/master/docs/contributing/readme.md) - написать любую проверку из списка ниже или любой другой инструмент улучшающий разработку по стандартам diff --git a/docs/checks/readme.md b/docs/checks/readme.md index 7c91dc75..194c0b33 100644 --- a/docs/checks/readme.md +++ b/docs/checks/readme.md @@ -2,9 +2,9 @@ - [Проверки поставляемые 1C:Enterprise Development Tools](edt.md) - Проверки 1C:Code Style V8 - - [Проверки метаданных](md.md) - - [Проверки Форм](form.md) - - [Проверки прав ролей](right.md) - - [Проверки модулей](bsl.md) - - [Проверки языка запросов](ql.md) + - [Проверки метаданных](md.md) + - [Проверки Форм](form.md) + - [Проверки прав ролей](right.md) + - [Проверки модулей](bsl.md) + - [Проверки языка запросов](ql.md) - [АПК Ред.1 индекс соответствия](acc_index.md) diff --git a/docs/contributing/check_description.md b/docs/contributing/check_description.md index f40d0f7a..3f4c89b5 100644 --- a/docs/contributing/check_description.md +++ b/docs/contributing/check_description.md @@ -2,15 +2,15 @@ 1. Создайте файл описания проверки на английском c идентификатором в имени файла - - Например: `com.e1c.v8codestyle.bsl/markdown/my-check-id.md` + - Например: `com.e1c.v8codestyle.bsl/markdown/my-check-id.md` 2. Создайте файл описания проверки на русском - - Например: `com.e1c.v8codestyle.bsl/markdown/ru/my-check-id.md` + - Например: `com.e1c.v8codestyle.bsl/markdown/ru/my-check-id.md` 3. Укажите - - Краткое название проверки - - Полное описание проблемной ситуации в коде или метаданных, того как работает проверка - - Добавьте пример неправильного кода - - Пояснение почему так делать не стоит - - Добавьте пример правильного кода + - Краткое название проверки + - Полное описание проблемной ситуации в коде или метаданных, того как работает проверка + - Добавьте пример неправильного кода + - Пояснение почему так делать не стоит + - Добавьте пример правильного кода Читайте подробнее [советы по наименованию и описанию](Check_Convention.md#наименование-проверки). diff --git a/docs/contributing/commits.md b/docs/contributing/commits.md index fe38ed20..e7ddc577 100644 --- a/docs/contributing/commits.md +++ b/docs/contributing/commits.md @@ -16,15 +16,15 @@ 1. Начинаем с номера задачи (например, #12311). Идентификатор необходим для интеграции с задачами GitHub 2. В качестве разделителя между номером задачи и заголовком коммита используем пробел. 3. Далее идет заголовок коммита: - - Пишем на русском языке. - - Заголовок с большой буквы. - - В конце заголовка точку не ставим. - - Желательно использовать настоящее время, а не прошедшее (например, "Исправление ошибок запуска при указанной web ИБ"). - - Рекомендуем писать не слишком длинный заголовок, так как его отображение во многих интерфейсах выполнено в одну строку без переносов, так что, он может не влезть. Подробные детали пишем отдельным параграфом в описании коммита. + - Пишем на русском языке. + - Заголовок с большой буквы. + - В конце заголовка точку не ставим. + - Желательно использовать настоящее время, а не прошедшее (например, "Исправление ошибок запуска при указанной web ИБ"). + - Рекомендуем писать не слишком длинный заголовок, так как его отображение во многих интерфейсах выполнено в одну строку без переносов, так что, он может не влезть. Подробные детали пишем отдельным параграфом в описании коммита. 4. Описание коммита (опционально). - - Отделяем от заголовка пустой строкой. - - Пишем полноценные предложения (начинаем с большой буквы, заканчиваем точкой) - - Хорошей практикой является ограничение длины строк в сообщении ≈72 символами, с добавлением переносов, если не влезает. Многие UI инструменты для GIT (в том числе EGit) не делают переносы текста описания, если он не влез. + - Отделяем от заголовка пустой строкой. + - Пишем полноценные предложения (начинаем с большой буквы, заканчиваем точкой) + - Хорошей практикой является ограничение длины строк в сообщении ≈72 символами, с добавлением переносов, если не влезает. Многие UI инструменты для GIT (в том числе EGit) не делают переносы текста описания, если он не влез. ### Контент сообщения коммита: @@ -33,16 +33,16 @@ 1. Заголовок должен быть ёмкий и информативный. 2. Заголовок должен быть написан официальным языком, без разговорных оборотов. 3. Чтобы определить достаточность детализации заголовка коммита, попробуйте ответить на вопрос, не заглядывая в код: - - `[Bug]` Какая конкретно проблема здесь исправлена? - - `[Feature]` Какая функциональность здесь добавлена? - - `[Refactoring]` В каких компонентах/классах произведен рефакторинг? - - `[Tests]` Что они тестируют? - - `[Baseline]` В каком компоненте/плагине/пакете подняли версию/версии? - - `[docs]` В каком компоненте добавлена документация? - - `[fix]` Какие именно проблемы вы исправили? + - `[Bug]` Какая конкретно проблема здесь исправлена? + - `[Feature]` Какая функциональность здесь добавлена? + - `[Refactoring]` В каких компонентах/классах произведен рефакторинг? + - `[Tests]` Что они тестируют? + - `[Baseline]` В каком компоненте/плагине/пакете подняли версию/версии? + - `[docs]` В каком компоненте добавлена документация? + - `[fix]` Какие именно проблемы вы исправили? 4. Зачем писать сообщение коммита? - - Когда сделанные изменения неочевидны коллегам, то, помимо комментария в самом коде, не будет лишним описать детальнее, зачем эти изменения были сделаны или, почему сделаны именно так, а не иначе. - - При исправлении сложных багов можно воспользоваться методологией [Root_cause_analysis](https://en.wikipedia.org/wiki/Root_cause_analysis), и указать причину ошибочного поведения, а так же каким образом это исправили. Человек (или даже вы сами), который через пару лет наткнется на неочевидное изменение, скажет вам спасибо. + - Когда сделанные изменения неочевидны коллегам, то, помимо комментария в самом коде, не будет лишним описать детальнее, зачем эти изменения были сделаны или, почему сделаны именно так, а не иначе. + - При исправлении сложных багов можно воспользоваться методологией [Root_cause_analysis](https://en.wikipedia.org/wiki/Root_cause_analysis), и указать причину ошибочного поведения, а так же каким образом это исправили. Человек (или даже вы сами), который через пару лет наткнется на неочевидное изменение, скажет вам спасибо. ## Количество коммитов diff --git a/docs/contributing/environment.md b/docs/contributing/environment.md index b05891f8..7f4fc7cb 100644 --- a/docs/contributing/environment.md +++ b/docs/contributing/environment.md @@ -8,13 +8,13 @@ 2. [1С:Starter](https://releases.1c.ru/project/DevelopmentTools10) дистрибутив 1C:EDT online, без установки самой 1C:EDT. 3. Установите дистрибутив `Eclipse for 1C:EDT Plug-ins Developers`, версия 2020-12 (см. актуальную версию в таргет-платформе для ветки `master`) - это стандартный дистрибутив Eclipse JDT с дополнительными плагинами и некоторыми настройками по умолчанию. 4. Установите плагины из Eclipse-Marketplace: - - `JAutodoc` - генерация "рыбы" java-doc на английском - по `CTRL+ALT+J` ускоряет написание документации - - `SonarLint` - подсказывает очень много проблем в коде и плохих практик - - `ResourceBundle Editor` - редактирование интерфейсных локализируемых файлов `*.properties` на нескольких языках - - `Enhanced Class Decompiler` - удобный просмотр классов без исходного кода - - `LiClipseText` - редактор поддерживающий множество синтаксиса, например Markdown - - `EclEmma Java Code Covarage` - Запуск тестов со снятием покрытия кода - - `PDE Source Lookup` - Автоматическая подгрузка исходников для бандлов из целевой платформы из открытых источников + - `JAutodoc` - генерация "рыбы" java-doc на английском - по `CTRL+ALT+J` ускоряет написание документации + - `SonarLint` - подсказывает очень много проблем в коде и плохих практик + - `ResourceBundle Editor` - редактирование интерфейсных локализируемых файлов `*.properties` на нескольких языках + - `Enhanced Class Decompiler` - удобный просмотр классов без исходного кода + - `LiClipseText` - редактор поддерживающий множество синтаксиса, например Markdown + - `EclEmma Java Code Covarage` - Запуск тестов со снятием покрытия кода + - `PDE Source Lookup` - Автоматическая подгрузка исходников для бандлов из целевой платформы из открытых источников ## Настроки JDT и проекта @@ -28,14 +28,14 @@ ## Настройка дополнительных плагинов - JAutodoc - - Использование встроенного форматера Eclipse `Preferences -> Java -> JAutodoc -> Use Eclipse formatter` - - Использование комментария от поля для Getter/Setter `Preferences -> Java -> JAutodoc -> [G,S]etter from field comment` + - Использование встроенного форматера Eclipse `Preferences -> Java -> JAutodoc -> Use Eclipse formatter` + - Использование комментария от поля для Getter/Setter `Preferences -> Java -> JAutodoc -> [G,S]etter from field comment` - ResourceBundle Editor - - Кодировка `*.properties` файлов UTF-8 `Preferences -> General -> Content types -> Text -> Java properties File` измените `Default encoditng = UTF-8` - - Отключить конвертацию юникода в ХХХ `Preferences -> ResourceBundle Editor -> Formatting -> Convert unicode values to \uXXXX` + - Кодировка `*.properties` файлов UTF-8 `Preferences -> General -> Content types -> Text -> Java properties File` измените `Default encoditng = UTF-8` + - Отключить конвертацию юникода в ХХХ `Preferences -> ResourceBundle Editor -> Formatting -> Convert unicode values to \uXXXX` - Enhanced Class Decompiler - - Выбор алгоритма по умолчанию `Preferences -> Java -> Decompiler -> Default class decompiler` = JD-Core (например) - - Установка просмотрщика классов по умолчанию `Preferences -> Java -> Decompiler -> Set Class Decompiler viewer as default...` + - Выбор алгоритма по умолчанию `Preferences -> Java -> Decompiler -> Default class decompiler` = JD-Core (например) + - Установка просмотрщика классов по умолчанию `Preferences -> Java -> Decompiler -> Set Class Decompiler viewer as default...` ## (Опционально) Список плагинов JDT в поставке от 1С diff --git a/docs/contributing/project_language.md b/docs/contributing/project_language.md index 5609ab18..061b5c33 100644 --- a/docs/contributing/project_language.md +++ b/docs/contributing/project_language.md @@ -2,17 +2,17 @@ - На **Английском** пишем: - - Исходный код проекта, имена классов, строковые литералы и т.д. - - Документирующие комментарии для разработчиков JavaDoc - - Основной интерфейс пользователя (default language) - - Код тестов JUnit - - Документация по проверкам в корне каталога `/check.descriptions/` (основной язык) - - Тестовый примеры кода 1С (желательно) + - Исходный код проекта, имена классов, строковые литералы и т.д. + - Документирующие комментарии для разработчиков JavaDoc + - Основной интерфейс пользователя (default language) + - Код тестов JUnit + - Документация по проверкам в корне каталога `/check.descriptions/` (основной язык) + - Тестовый примеры кода 1С (желательно) - На **Русском** пишем: - - Второй дополнительный интерфейс - - Документация по проверкам в каталога `/check.descriptions/ru/` - - Тестовый примеры кода 1С (допустимо) + - Второй дополнительный интерфейс + - Документация по проверкам в каталога `/check.descriptions/ru/` + - Тестовый примеры кода 1С (допустимо) ## Подробнее... diff --git a/docs/contributing/readme.md b/docs/contributing/readme.md index 7e6867cb..1c468ecd 100644 --- a/docs/contributing/readme.md +++ b/docs/contributing/readme.md @@ -3,30 +3,30 @@ Здесь описаны советы, как сделать свое участие наиболее эффективным для проекта и для себя. - Старт - - [Настройка окружения](environment.md) - - [Соглашение по стилю кодирования (Code Style)](code_style.md) - - [Язык проекта, локализация интерфейса](project_language.md) - - [JavaDoc платформы 1C:EDT](https://edt.1c.ru/dev/edt/2021.2/apidocs/) + - [Настройка окружения](environment.md) + - [Соглашение по стилю кодирования (Code Style)](code_style.md) + - [Язык проекта, локализация интерфейса](project_language.md) + - [JavaDoc платформы 1C:EDT](https://edt.1c.ru/dev/edt/2021.2/apidocs/) - Разработка проверок - - [Процесс разработки проверки](check_workflow.md) - - [Пример разработки простой проверки](check_example.md) ([Видео пример](https://youtu.be/Q_JtIVTntiM)) - - [Соглашение при создании проверок](Check_Convention.md) - - [Тесты по проверкам (JUnit)](testing.md) + - [Процесс разработки проверки](check_workflow.md) + - [Пример разработки простой проверки](check_example.md) ([Видео пример](https://youtu.be/Q_JtIVTntiM)) + - [Соглашение при создании проверок](Check_Convention.md) + - [Тесты по проверкам (JUnit)](testing.md) - Создание документации - - [Документация в составле плагина](documentation.md) - - [Описание проверок](check_description.md) + - [Документация в составле плагина](documentation.md) + - [Описание проверок](check_description.md) - Разработка инструментов - - [Общие сведения по разработке плагинов](https://edt.1c.ru/dev/ru/docs/plugins/dev/) - - [Целевая платформа / Target platform 1C:EDT](https://edt.1c.ru/dev/ru/docs/plugins/dev/target-platform/) - - [Точки расширения](https://edt.1c.ru/dev/ru/docs/plugins/dev/extension-points/) - - [Разработка пользовательского интерфейса](https://edt.1c.ru/dev/ru/docs/plugins/dev/ui/) - - [Публичные сервисы - Общая информация](https://edt.1c.ru/dev/ru/docs/plugins/dev/public-services/) - - [Cервисы общего назначения 1C:EDT](https://edt.1c.ru/dev/ru/docs/plugins/dev/edt-services/) - - [Работа с модулями встроенного языка (bsl)](https://edt.1c.ru/dev/ru/docs/plugins/dev/lang/) - - [Модель встроенного языка (bsl)](https://edt.1c.ru/dev/ru/docs/plugins/dev/lang/bsl-model/) + - [Общие сведения по разработке плагинов](https://edt.1c.ru/dev/ru/docs/plugins/dev/) + - [Целевая платформа / Target platform 1C:EDT](https://edt.1c.ru/dev/ru/docs/plugins/dev/target-platform/) + - [Точки расширения](https://edt.1c.ru/dev/ru/docs/plugins/dev/extension-points/) + - [Разработка пользовательского интерфейса](https://edt.1c.ru/dev/ru/docs/plugins/dev/ui/) + - [Публичные сервисы - Общая информация](https://edt.1c.ru/dev/ru/docs/plugins/dev/public-services/) + - [Cервисы общего назначения 1C:EDT](https://edt.1c.ru/dev/ru/docs/plugins/dev/edt-services/) + - [Работа с модулями встроенного языка (bsl)](https://edt.1c.ru/dev/ru/docs/plugins/dev/lang/) + - [Модель встроенного языка (bsl)](https://edt.1c.ru/dev/ru/docs/plugins/dev/lang/bsl-model/) - Общие вопросы по проекту - - [Лицензирование кода](licensing.md) - - [Оформление задачи](issue.md) - - [Правила оформления коммитов](commits.md) - - [Оформление "запроса на слияние" (Pull request)](pull_request.md) - - [Версионирование проекта](versioning.md) + - [Лицензирование кода](licensing.md) + - [Оформление задачи](issue.md) + - [Правила оформления коммитов](commits.md) + - [Оформление "запроса на слияние" (Pull request)](pull_request.md) + - [Версионирование проекта](versioning.md)