The following text is a partial translation of the original English article, performed by ChatGPT (gpt-3.5-turbo) and this Jekyll plugin:
Несколько недель назад кто-то предложил мне попробовать интегрировать правила статического анализа IntelliJ IDEA в Qulice, наш агрегатор Checkstyle, PMD, FindBugs и некоторых других анализаторов. Я действительно люблю правила IDEA - некоторые из них уникальны и очень полезны. Я спросил, можно ли найти их где-то в Maven Central (они написаны на Java), и ответ был: “Тебе придется самому разобраться, как их использовать, но они открытые исходники”. Вот мое мнение об этой ситуации: я считаю, что открытый исходный код - это не только возможность прочитать его без разрешения. Это означает нечто гораздо большее.
Публичный доступ к коду - это не все, что требуется, чтобы назвать программное обеспечение открытым исходным кодом. На самом деле, это только наносит вред продукту и репутации его автора, если он открыт, но не готов к повторному использованию (что является главной целью открытого исходного кода). Как сказал Эрик Рэймонд в его знаменитой работе Кафедральный и базар: “Хорошие программисты знают, что написать. Великие знают, что переписать (и повторно использовать).”
Ответственность за помощь этим “хорошим” программистам в повторном использовании кода лежит на авторе программного продукта. Написание кода, тестирование, отладка и проверка на “работает на моем ноутбуке” - это одно. Сделать его читаемым и повторно используемым - совершенно другая работа, которая может занять гораздо больше времени.
Как сказал Карл Фогель в Производство открытого программного обеспечения: “Большинство проектов свободного программного обеспечения терпят неудачу”. Они терпят неудачу (наряду с множеством других факторов), потому что недостаточно внимания уделяется следующим основным вещам (в произвольном порядке):
Я уверен, что вы размещаете свой продукт на GitHub. (Если нет, что с вами не так?) В корневом каталоге должен быть файл README, который объясняет, о чем вообще продукт и как его использовать. Несколько хороших примеров: leejarvis/slop, mongobee/mongobee ronmamo/reflections, и yegor256/takes (этот мой). Несколько плохих примеров: qos-ch/slf4j, rzwitserloot/lombok, и junit4/blob (не будьте как эти ребята).
Независимо от того, насколько вы разнообразили свой сайт, Javadoc, Wiki, рассылку и Twitter, README - это место, где мы ожидаем увидеть все. Только если и когда мы заинтересуемся, мы будем исследовать дальше и глубже. Прочитайте README-файлы в других проектах и скопируйте их лучшие идеи. README - это ваша витрина, она должна сиять.
Большинство из нас не обращает внимания на эту бюрократию. Я тоже не обращал внимания, пока недавно. Я думал, что когда мой код открыт, я могу забыть о любых правах и роялти. Они просто будут использовать мой код, и я никогда не увижу никакой прибыли. Лицензия, которую я к нему прикрепляю, не имеет значения - все равно никто ее не читает. Это и происходит в большинстве случаев. Но только пока эти пользователи не являются важными.
Несколько лет назад я был архитектором на проекте по разработке программного обеспечения, и нам нужно было создать анализатор аппаратных компонентов, таких как ЦП, память, жесткий диск и т. д. Нам нужно было убедиться, что все они работают как ожидается после выполнения довольно сложных и настраиваемых тестов. Моим очевидным предложением было использование инструментов с открытым исходным кодом, которые выполняли бы сложную работу за нас. Нам бы только нужно было их интегрировать. Это была замечательная идея, пока некоторые из нас не решили проверить лицензии этих инструментов.
Вот тогда я понял, что был настолько неправ, игнорируя то, что говорят лицензии. GPL, например, которую мы обнаружили в нескольких инструментах, не позволяла нам использовать код, если наш продукт не являлся свободным. Так как мы создавали проприетарное программное обеспечение, мы поняли, что не можем использовать модули с копилефтным лицензированием, только MIT, BSD или подобные.
Я предлагаю вам задуматься о лицензии перед публикацией продукта. С 2016 года я использовал MIT во всех своих продуктах.
Простая коллекция файлов .rb не является переиспользуемым кодом на Ruby. Ну, может быть, для тех хакеров, которых я так сильно презираю, это так. Но для профессиональных разработчиков, которые слишком ленивы читать свой собственный код, не говоря уже о коде других людей, это определенно не так.
“Возьми это с GitHub” больше не является вежливым способом обращаться к нам - вашим коллегам-программистам. Это было так двадцать лет назад, но сейчас у нас есть хранилища. Вам нужно распространять свой продукт в виде “артефакта” через одно из этих публичных хранилищ и сделать его доступным для загрузки оттуда, пропустив тестирование и упаковку, и просто использовать его как продукт (например, Ruby-гем или Java JAR).
Я говорю о хранилищах вроде Maven Central, npmjs или RubyGems. Вам нужно найти способ развернуть свой продукт там. Это не простая задача, хотя эти хранилища делают все возможное, чтобы упростить процесс. Во всех наших проектах мы используем Rultor, который помогает нам оптимизировать развертывание.
“yegor256/xcop в RubyGems (подробности);”
yegor256/tacit в npmjs.
Менеджеры пакетов, такие как Maven, NPM, Rake, Grunt, Gradle и другие, являются стандартным и традиционным способом повторного использования открытого исходного кода (а также собственного). Если ваш продукт недоступен в общедоступном репозитории, это не продукт; это просто кодовая база.
Мы все ненавидим написание документации. И мы ненавидим библиотеки, которые не документированы. Мне обычно скучно писать блоки Javadoc для моих классов, но я понимаю, что без них код, который я пишу внутри этих классов, не заинтересует никого.
Лучший формат для этих блоков Javadoc - “на примере”. Вместо прозы я бы порекомендовал вам продемонстрировать, как использовать класс, особенно в сочетании с его соседями. Более того, я бы предложил вам не писать документацию нигде, кроме этих блоков Javadoc. (Они существуют и на других языках, но имеют другие имена.)
Проблема с Javadoc заключается в том, что не так легко отформатировать текст так, чтобы он выглядел визуально привлекательно. Возможно, поэтому многие программисты все еще полагаются на Вики или веб-сайты проектов. Я бы порекомендовал вам оставаться внутри блоков Javadoc и изучить их синтаксис форматирования.
Как вы можете видеть, мне нравятся значки. Прежде всего, они придают репозиторию вид “активно поддерживаемого”, особенно если эти значки зеленые. На самом деле они не несут никакой ценной информации. Они в основном говорят: “У нашего автора очень хороший вкус, посмотрите, как наши цвета идеально сочетаются!”
Шутки в сторону, не так просто добавить все эти значки. Каждый значок потребует некоторого времени на интеграцию сторонней системы, на то, чтобы убедиться, что числа достаточно хорошие, чтобы гордиться ими, и чтобы держать все это под контролем. Если репозиторий не наблюдается, значки в конечном итоге начнут отказывать.
Чтобы использовать ваш код, нам нужно доверять ему, то есть быть уверенными, что он работает или по крайней мере проходит автоматические тесты. (Нужно ли говорить, что у вас должны быть тесты?) Как мы можем быть уверены, что он работает? Ответ - CI. Мы должны иметь возможность видеть журналы последней сборки CI и убедиться, что они чистые.
Это вопрос доверия. Вы можете никогда не использовать эти сборки Travis и просто игнорировать их красные и зеленые сигналы, но они важны для нас - ваших клиентов. Я добавляю значки Travis во все свои проекты сразу после создания нового репозитория.
Для обычного наркомана GitHub не составляет проблемы разобраться, как отправить вам запрос на объединение. Однако большинство из нас, по крайней мере вначале, будут активными пользователями, а не участниками проекта. Мы попытаемся использовать ваш продукт и настроить его под свои нужды. Если мы заблудимся, мы уйдем, разочарованные.
Чтобы этого избежать, вам необходимо объяснить, что должен делать дисциплинированный участник, чтобы внести изменения в ваш код. Вот вопросы, которые я рекомендую вам ответить в вашем CONTRIBUTING.md:
На сколько большой/маленький должен быть запрос на слияние (pull request), чтобы его можно было принять?
“Каковы ваши руководящие принципы стиля?”
Как должны быть сообщены, помечены и объяснены ошибки?
Что делает хороший отчет об ошибке?
Вот текст, который я использую во всех своих проектах: ISSUE_TEMPLATE.md и PULL_REQUEST_TEMPLATE.md.
Наконец, если вам повезет, мы будем использовать ваш продукт и заинтересуемся внесением вклада. Вы начнете получать наши pull-запросы. Вопрос в том, как быстро мы сможем испортить ваш кодовую базу. Мы это сделаем, если вы не защитите себя.
Если вы строго проверяете каждый pull-запрос и отклоняете всё, что не выглядит как “отличный” код, вы потеряете нас, ваших вкладчиков. Мы не хотим писать отличный код, мы хотим вносить изменения в ваш продукт, чтобы он стал более подходящим для наших потребностей. Великолепие кода - это ваша забота, а не наша.
С другой стороны, если вы принимаете все, что поступает, архитектура потеряет свою надежность (если она вообще была) и вы снова потеряете нас, ваших вкладчиков. В этот раз вы потеряете нас, потому что продукт станет плохим и сложным в поддержке и внесении вклада.
Самый лучший способ сохранить баланс - это “нанять” инструмент, который поможет вам: автоматизация сборки, статический анализ, автоматическое тестирование и контроль покрытия. Вам нужно настроить продукт на отказ, когда изменения, которые кто-то вносит, нарушают его внутренние ожидания качества. Я также использую для этого Rultor.
Я что-то забыл?
Translated by ChatGPT gpt-3.5-turbo/42 on 2023-11-28 at 15:05
