Skip to content

Latest commit

 

History

History
61 lines (37 loc) · 6.34 KB

StyleGuide.md

File metadata and controls

61 lines (37 loc) · 6.34 KB
Raw

Руководство по стилю написания кода

В данном документе собраны общие рекомендации по написанию кода в проекте BSL Language Server.

Постарайтесь придерживаться их, и процесс ревью Вашего кода будет гладким и шелковистым (с).

Общие рекомендации

Если метод на законных основаниях может возвращать null, рекомендуется вместо явного возврата null возвращать Optional<T>. Исключения (например, высокочастотные или перфомансные функции) обговариваются отдельно.

Форматирование

  1. Весь код в модулях должен быть автоматически отформатирован.
  2. Оступы - пробелами
  3. Размер отступа - 2 символа. Continuous indent - тоже два символа. В IntelliJ IDEA настройка отступов по схеме 2-2-2

Расположение членов класса

  1. Расположение полей, методов, модификаторов в целом должно соответствовать рекомендациям Oracle - File organization, и SonarSource - Modifiers should be declared in the correct order
  2. Методы рекомендуется размещать в следующем порядке:
    1. public методы объекта
    2. protected/package private методы объекта
    3. private методы объекта
    4. public методы класса
    5. protected/package private методы класса
    6. private методы класса

Статический анализ

Код BSL Language Server автоматически проверяется на соответствие стандартам кодирования на сервисе SonarCloud - ссылка на проект.

Список активированных правил и их настройки можно посмотреть в профиле качества 1c-syntax way.

В силу имеющихся ограничений безопасности пулл-реквесты не из репозитория 1c-syntax/bsl-language-server не проверяются на соответствие стандартам. После принятия пулл-реквеста рекомендуется зайти на страницу проекта на SonarCloud и просмотреть список замечаний с фильтрацией по автору. Пулл-реквест с исправлением замечаний приветствуется.

Линтер

Для улучшения качества кода и предварительной проверки на соответствие стандартам рекомендуется установить в Вашу IDE плагин SonarLint.

Для автоматического скачивания и параметризации правил в соответствиями с настройками на SonarCloud может потребоваться "биндинг" локального проекта к проекту SonarCloud. Если в Вашей IDE не получается найти соответствующий проект на SonarCloud, обратитесь к мэйнтейнерам проекта за добавлением Вас в список "Members" на SonarCloud.

Логирование

Для логирования используется библиотека Slf4j. Использование вывода в System.out и System.err допустимо только в исключительных случаях (например, в обработчиках cli-команд).

Для упрощения создания экземпляра логгера рекомендуется навешивать аннотацию @lombok.extern.slf4j.Slf4j на объявление класса.

Документирование

  1. Каждый новый класс обязан иметь javadoc-описание класса. Исключение - классы, реализующие интерфейсы BSLDiagnostic или QuickFixSupplier.
  2. Каждый новый package обязан иметь package-info.java с javadoc-описанием пакета.
  3. Каждый новый публичный метод в utils-пакете, классах-хелперах или классах, уже имеющих javadoc-описания, обязан иметь javadoc-описание метода.

Внешние зависимости

  1. Подключение новых библиотек в implementation scope стоит производить аккуратно, с контролем увеличения размера итогового jar-файла. По возможности "лишние" и незадействованные суб-зависимости стоит исключать через exclude.
  2. Явное подключение библиотеки com.google.guava, Google Collections или прочих частей библиотек семейства Guava запрещено. В случае крайней необходимости допустимо копирование реализации из Guava внутрь BSL Language Server с выполнением условий лицензии Guava. Для всего остального есть Apache Commons.
  3. Прямой импорт классов *.google.*, а так же прочих частей библиотек Guava запрещено. Без исключений.

В процессе наполнения...