Перейти к содержанию

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

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

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

Обработка null

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

В описании пакета package-info.java необходимо указать, что в пакете по умолчанию используется NonNull API. Для этого над именем пакета добавляется аннотация @DefaultAnnotation(NonNull.class)

Пример: 

// ...Лицензия...
@DefaultAnnotation(NonNull.class)
package com.github._1c_syntax.bsl.languageserver;

import edu.umd.cs.findbugs.annotations.DefaultAnnotation;
import edu.umd.cs.findbugs.annotations.NonNull;

Для явного указания того, что метод может принимать или возвращать null, используется аннотация @edu.umd.cs.findbugs.annotations.Nullable.

В общем случае это позволяет не использовать аннотации @edu.umd.cs.findbugs.annotations.NonNull вообще.

Аннотации по контролю за null из пакета javax.annotations или jetbrains.annotations использоваться не должны.

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

  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 запрещено. Без исключений.
  4. Пакет jsr305 и его аннотации не должны использоваться в коде. См. раздел "Обработка null".

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