Кодовые руководства Jdbi

Мы стремимся найти здоровое равновесие между субъективным совершенством и практическими соображениями, но мы решительно против того, чтобы делать работу быстро и незаконченной, которая потребует больше последующей работы.

• Используйте современный JDK. По крайней мере, последний LTS (Java 21 сейчас) или новее.
• Когда возможно, используйте "говорящие" имена. handle, а не h.
• Минимизируйте изменения в коде. Если вы можете скрыть внутренний класс, сделайте это. Если вы можете сделать внутренний класс final, сделайте это.
• Jdbi — это библиотека, и любой зависимости, которую мы используем, мы также навязываем пользователям. Минимизируйте количество зависимостей.

Текст был полностью переведён, сохранив исходное форматирование и структуру.* Лучше использовать беспоточные, неизменяемые объекты вместо всего остального.

• Мы любим как конструкторы, так и методы завода/строителей, но требуем, чтобы они использовались правильно. Конструкторы отлично подходят для простых классов, заводы лучше, когда требуется любая защитная логика.
• Некоторые фундаментальные классы (Jdbi, всё, связанное с конфигурацией) должны быть многопоточными. Другие (например, Handle и классы запросов) нет. Ясно указывайте, если класс должен быть однопоточным (может использоваться только одним потоком), многопоточным (может использоваться несколькими потоками одновременно) или между этими двумя вариантами (например, может использоваться несколькими потоками, но только одним потоком за раз). Если класс не безопасен для использования несколькими потоками, явно укажите это.

Пожалуйста, выполните make clean install локально перед открытием PR. Мы выполняем множество проверок кода и стилистики на полной сборке, и неудачи этих проверок на PR означают, что мы не будем рассматривать PR до тех пор, пока эти проблемы не будут исправлены. Ваш локальный запуск сборки из командной строки должен пройти успешно.

Обратная совместимость

Jdbi уделяет серьёзное внимание тому, чтобы не нарушать обратную совместимость. Вспомните эти простые правила и подумайте дважды перед тем, как сделать какие-либо классы или члены классов public!

1. то, что попадает в API, остаётся там (или: нет временно, но да — навсегда);
2. если часть API должна быть осуждена после публичного выпуска, пометьте её @Deprecated и оставьте её функционально целой;
3. работа по удалению старого кода может быть выполнена, когда Jdbi готовится к увеличению версии (см. SemVer);
4. исправления ошибок, которые абсолютно требуют изменения API, являются единственным исключением.

Если вам необходимо сделать некоторые внутренние классы public, чтобы получить доступ к ним из других пакетов, поместите класс в пакет с названием internal. Пакеты с таким названием не считаются API.

Прямая совместимость

Совершенно новые API должны быть помечены с помощью @Alpha или @Beta. Это позволяет пользователям знать, что они ещё не могут сильно полагаться на ваши изменения, поскольку публичный выпуск может показать, что требуется больше работы.

Функциональность

Jdbi должен быть полезен для максимального количества проектов с минимальными усилиями, где это возможно. Он должен быть полезен прямо из коробки с разумными значениями по умолчанию, но всегда настраиваемым до степени, необходимой пользователям.

Тестирование

• Мы используем JUnit 5 для всех наших тестов и assertj как фреймворк утверждений.
• Наши тесты описывают и проверяют поведение Jdbi, изменения которого необходимо обсуждать, и мы отклоним ненужные изменения тестов.
• Запустите базу данных с помощью одного из ядерных тестовых фреймворков (H2DatabaseExtension и PgDatabaseExtension) если вы вносите свой вклад в основной репозиторий или расширений тестирования (JdbiExtension) для всех остальных модулей.
• Сначала сосредоточьтесь на функциональности и ясности тестов, заботьтесь о производительности потом. (Полная сборка, выполняющая около 1650 тестов против сотен запущенных и остановленных экземпляров PostgreSQL и H2, занимает примерно 200 секунд с использованием JDK 19, mvnd на MacBook Pro 2021 года. И мы выполняем тесты на CI.)
• Не используйте моки или любые фреймворки мока в тестах. Мы используем Mockito в нескольких местах, и каждый раз это проблема и трудно поддерживать.

Использование моков и фреймворков мока обычно не рекомендуется. Есть несколько существующих тестов, которые используют Mockito, и они являются проблемой и трудно поддерживаются.

Разработка

Большинство современных IDE настраиваются правильно путём импорта репозитория Jdbi как проекта Apache Maven. Если необходимо, установите поддержку для Apache Maven.

Кодовый стиль / правила форматирования

Проект использует набор правил стиля кода и форматирования. Эти правила применяются через Checkstyle и PMD как часть процесса сборки.

Мы не рассматриваем или объединяем PR, которые не проходят наши предварительные проверки перед слиянием. Выполните сборку локально с помощью make install.

Сборка управляемая Make

На уровне корня проекта находится файл Makefile для управления различными сборками. Выполните make или make help, чтобы просмотреть все доступные цели. Некоторые цели имеют привилегии (вы должны быть участником команды разработки Jdbi). Общедоступные цели включают:

* clean               - очистить локальное дерево сборки
* install             - выполнить сборку, статический анализ и юнит-тесты, затем установить в локальном репозитории
* install-notests     - то же самое, что и 'install', но пропустить юнит-тесты
* install-nodocker    - то же самое, что и 'install', но пропустить юнит-тесты, требующие локальной установки Docker
* install-fast        - то же самое, что и 'install', но пропустить юнит-тесты и статический анализ
* tests               - выполнить сборку кода и запустить юнит-тесты и интеграционные тесты, кроме действительно медленных тестов
* docs                - выполнить сборку актуальной документации в docs/target/generated-docs/
* run-tests           - запустить все юнит-тесты и интеграционные тесты, кроме действительно медленных тестов
* run-tests-nodocker  - то же самое, что и 'run-tests', но пропустить все тесты, требующие локальной установки Docker
* run-tests-container - запустить полный много-базовый контейнерный тестовый набор

• Если вы делаете изменения в коде Jdbi, пожалуйста, выполните make tests перед открытием PR.
• Если вы делаете изменения в документации, пожалуйста, выполните make docs перед открытием PR.Если у вас нет локальной установки Docker (необходимо для некоторых тестов), используйте эквивалентные цели -nodocker.

IntelliJ IDEA

• Форматирование IntelliJ IDEA.

Eclipse IDE

• Правила форматирования Eclipse.

Импортируйте эти настройки через Preferences → Java → Code Style → Formatter → Import... и активируйте их для всех модулей Jdbi.

• Порядок импортов в Eclipse.

#Организация порядка импортов
0=java.*
1=javax.*
2=
3=\#java.*
4=\#javax.*
5=\#

• Откройте свойства вашего проекта
• Перейдите к Preferences → Java → Code Style → Organize Imports
• Нажмите кнопку Import... и выберите созданный ранее файл
• Установите большое значение для обоих полей Number of [static] imports needed for . (например, 1000), чтобы отключить использование звездочек
• Закройте диалоговое окно
• Перед любым коммитом используйте эти правила для организации импортов в изменённых файлах

Инструкции по импорту Java

Мы требуем следующий порядок импортов:

java.*

javax.*

*

static java.*

static javax.*

static *

Между каждой группой обязательна пустая строка. Импорты внутри группы должны быть расположены в алфавитном порядке.

Звёздочные (или "wildcard") импорты, включая статические, не допускаются.

Документация Javadoc не должна вызывать импорт, то есть следует использовать полностью квалифицированные названия классов (Fully Qualified Class Names, FQCN) в Javadoc, если класс уже был импортирован кодом.

Включение флага компилятора -parameters

Большинство наших тестов объектов SQL зависят от названий параметров методов SQL. Однако по умолчанию javac не компилирует эти названия параметров в файлы .class. Поэтому для прохождения юнит-тестов компилятор должен быть настроен на вывод названий параметров.

IntelliJ IDEA

• File → Settings
• Build, Execution, Deployment → Compiler → Java Compiler
• Дополнительные параметры командной строки: -parameters
• Нажмите Apply, затем OK.
• Build → Rebuild Project

Eclipse IDE

• Window → Preferences → Java → Compiler
• Раздел Classfile Generation
• Выберите чекбокс Add variable attributes to generated class files (used by the debugger)
• Выберите чекбокс Store information about method parameters (usable via reflection)
• Нажмите Apply и закройте диалоговое окно