Недавно узнал, что существуют конкурсы Open Source кода, где ранжируют проекты (совокупное количество баллов) по общему представлению и соответствию хороших практик. В общем, этот пост - это аккумулированные комментарии/критерии экспертов идеального открытого кода без воды.
Полезно тем, кто:
Не знаком с бест практикам.
Просто хотел бы узнать какие могут быть критерии таких конкурсов.
Кто хочет сделать свой проект более привлекательным.
Общее
Хорошие практики:
Присутствуют соглашения по использованию коммитов (Conventional Commits - все коммиты в едином стиле).
Сгенерировано с помощью AI, простите 🙏🥺🙏 Баги с четким описанием (STR).
Есть подробная документация.
Много релизов с детальным описанием.
Если библиотека, то создается для многих платформ.
Каждая feature/fix разрабатывается в своей собственной ветке, с номером выпуска, нет мертвых веток, есть ветки для релизных версий.
Есть Labels для Issues.
Как бонус (окак), есть активные/закрытые доски в разделе Projects в GitHub.
Сам недавно узнал, что существуют такие доски в GitHub, прикольно.
Сомнительные практики:
Неактивный проект.
Редкие релизы.
Пропуск релизных версий.
Есть Issues, где люди жалуются, что документация где-то ошибочна.
Релизы не имеют описания либо не полные.
Пример как можно, хотя тут не адаптировано для пользователей. Проект с одним рабочим пространством; может быть разбит на несколько модулей.
Репозиторий слишком большой. Веб-сайт, core пакет и CLI (+ фронтенд, бэкенд и т.д.) находятся в одном репозитории. Мюсли вслух: "Смотря какого подхода репозиториев вы придерживаетесь: 1) монорепозиторий или 2) на каждый проект свой репозиторий. Разумеется, когнитивно проще воспринимать маленькие репозитории".
Не понятный принцип разделения по пакетам.
Одна ветка для нескольких Issues.
В коде игнорируются ошибки линтера.
Сложно определить, где используется линтер/статический анализатор.
Слишком детальная документация (сайт), текста больше, чем самого кода.
Есть сайт с руководством по использованию приложения, но в руководстве отсутствует навигация, из-за чего пользоваться руководством может быть неудобно.
Код
✅:
Существует комплексная обработка исключений.
Ясные названия переменных.
Методы/функции маленькие, что удобно для их чтения.
❌:
Коммиты прямиком в мастер/мейн ветку.
Ad-hoc нумерация релизов (1.0.0+20250314 или 1.0.0.build452).
Есть stale ветки (ветки, которые давно не обновлялись и потеряли актуальность относительно основной ветки разработки - такие ветки нужно удалять).
Много крупных методов/функций (> 100 линий).
Отсутствие интерфейсов (меньше гибкости в тестировании).
Часто интерфейсы имеют только одну реализацию.
Некоторые объекты имеют излишне малый уровень детализации, что делает код многословным.
Методы/функции имеют слишком большую цикломатическую сложность (большое количество точек принятия решений (ветвления, циклы, операторы if, case, while и т.д.)).
Отсутствуют подробные комментарии к особо важным и сложным разделам библиотеки.
Большое количество параметров в методе.
Картинка взята из рефакторинг гуру. Как раз там решения такой проблемы. Присутствуют ненужные комментарии в коде.
Присутствует закомментированный код.
Много лишних пустых строк внутри тела метода.
Странное форматирование: private методы смешаны с public (не сгруппированы вместе).
Различный уровень абстракций на том же package уровне.
Много магических чисел.
Return null, когда этого можно избежать.
Отсутствие шаблонов проектирования в местах, где они могут быть применены (большой условный (case) оператор ⇒ паттерн состояние/стратегия).
В среднем файл содержит 250-500 строк, что слишком много.
Есть узкие места в производительности. Мюсли вслух: "Но помните..."
Дональд Эрвин Кнут (не забываем как выглядит дядюшка) Преждевременная оптимизация — корень всех зол.
Неиспользуемые импорты в файлах.
Windows, JetBrains IDE: Ctrl + Alt + O.
Windows, VS Code: Shift + Alt + O.
MacOs, JetBrains IDE: ⌃⌥O (Control + Option + O).
MacOs, VS Code: ⇧⌥O (Shift + Option + O).
Тесты
✅:
Есть контроль покрытия т��стами >60-80%.
Есть несколько видов тестов: unit, ui + e2e, интеграционные, performance тесты. Мой пример, e2e тестов в Android проекте.
Unit тесты декомпозированы и небольшие.
❌:
С каждым новым релизом падает покрытие тестов (87%>79%>65%>47%).
Тестовые файлы слишком большие (~1000 линий кода).
Тестовые данные подготавливаются непосредственно внутри теста, что делает файл тестирования чрезвычайно эффективным (я, например, в своем последнем проекте для android, подготовил отдельный модуль для таких данных, чтобы шарить между ui и unit тестами, и которые бы не были видны в самом клиентском коде).
Тесты проводятся только на Ubuntu, что затрудняет предоставление каких-либо гарантий для macOS и Windows.
В тестах используются проверки (assertions), которые при падении не дают никакой внятной информации о том, что именно пошло не так.
Как можно: assertEquals("Expected name:", expectedUser.name, actualUser.name) 
Тесты не проверяют критические сценарии.
Использование if-else внутри тестов.
Трудно понять, что делают некоторые тесты.
Проверка покрытия тестами выполняется при каждом commit`е в каждой ветке. Мюсли вслух: "У меня ещё была проблема с частым редактированием файла Readme.md, что постоянно триггерило CI/CD, в итоге добавил в игнор папку Readme для всех языков".
Пример из моего кода
Readme
✅:
Понятная цель проекта в README.md.
Хочется пользоваться проектом после прочтения Readme.
Присутствует локализация (повышает удобство использования для широкого круга пользователей).
Приведены примеры использования библиотеки.
Присутствует доп. документация CHANGELOG, CODE_OF_CONDUCT, LICENSE.
❌:
Нет описания как сбилдить проект.
Скупое README.md, все документы только на сайте, в файле нет быстрой installation/usage.
Битые ссылки в README.md.
Readme есть только на вашем родном языке (не английский).
Беспорядок и большое количество эмодзи в README.md.
Где-то на просторах интернета. Не Readme, но все же страшный Emoji Hell. P.s. Шакалы пришли - суету навели.
CI/CD + Pull Requests
✅:
Линтер, как часть CI.
Линтер отрабатывает только на master/main ветке.
Есть CI для релизов.
Есть CI для деплоя/валидации документации.
Есть CI для шаблонов PR/Issues.
PULL_REQUEST_TEMPLATE.md Review даже для PR от владельца самого репозитория.
Есть описания к PRs.
Есть ссылки на решаемую проблему (Issues) в PRs.
Release pipeline не задокументирован (через месяц можно забыть, как собирать релиз + контрибьюторы не смогут понять, как работает сборка).
Есть предварительное окружение для PRs.
❌:
Нет CI/CD.
Нет однострочного сценария сборки.
Ручные релизы.
PRs сливаются с failed CI статусами.
Один GitHub workflow.
Большинство PRs - это обновления зависимостей.
Много незакрытых PRs.
Очень большой PR.
CI сломан практически на всех коммитах в мастер.
Contribution
✅:
Детальный раздел для контрибьюторов/отдельный сайт.
Присутствует точный перечень правил (rules) для contribution.
❌:
Нет раздела Call-to-actions для контрибьюторов или CONTRIBUTION.md файла.
Контрибьютору нужно ждать продолжительное время на ответы от мейнтейнера в PR/Issues.
Нет практики Код Ревью - один контрибьютор (сам автор).
Один мейнтейнер, так что нет cross-review (bus factor = 1).
Картинка взята из статьи на Хабр про Bus-Factor Code Review почти не содержат рекомендаций (или токсичные).
Вот и всё, спасибо, что прочитали! Как считаете, что бы вы ещё добавили или может быть что-то кажется вам спорным, буду рад почитать, а по возможности ответить в комментариях.
P.s. Некоторые разделы довольно очевидны, другие буквально “смотря сколько details смотря какой fabric”, надеюсь, все равно было интересно и ваши окуляры не запотели от духоты (как мои)
