Почему нет обзоров кода для проектов с открытым исходным кодом? [закрыто]

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

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

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

Но все же я никогда не видел ни одного из этих «обзоров кода». Почему? Есть ли такие вещи, и я скучаю по ним? Вещи, которые делают ту же работу, что я описываю? Или это совершенно бесполезная идея, поскольку все, кроме меня, могут легко понять проекты с тысячами строк кода?

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

Многие программисты не хорошие технические писатели (хотя многие из них); они редко пишут документы исключительно для потребления человеком, поэтому у них нет практики и они не любят это делать. Написание обзора кода занимает время, которое вы не можете потратить на кодирование, и первоначальная выгода для проекта всегда будет больше, если вы скажете: «Мы поддерживаем все три варианта кодирования», а не «У нас действительно четкие объяснения нашего кода!» Идея о том, что такой документ привлечет больше разработчиков, так что в конечном итоге будет написано больше кода, не совсем чужды им, но воспринимается как неопределенная игра; будет ли этот текст действительно иметь значение между зацепкой коллаборациониста или нет? Если я продолжу кодировать прямо сейчас , сделай это

Обзорный документ кода также может заставить людей чувствовать себя защищенными; Трудно описать решения более высокого уровня, не чувствуя необходимости их оправдывать, и очень часто люди принимают решения без причины, которая «звучит достаточно хорошо», когда фактически написана самостоятельно. Существует также эффект, связанный с вышеупомянутым: поскольку обновление текста в соответствии с изменяющимся кодом требует дополнительных усилий, это может препятствовать быстрым изменениям кода. Иногда эта стабильность - хорошая вещь, но если код действительно нуждается в переписывании среднего уровня, это превращается в пассив.

Сухая, суровая правда?

Документация не составлена, потому что проекты могут обойтись без нее.

Даже проекты с открытым исходным кодом часто сталкиваются с жесткой конкуренцией. Большинство таких проектов не начинаются с больших плеч, они начинаются с яркой идеи, часто с идеей одного человека.

Таким образом, они не могут позволить себе потратить время и средства на найм документаторов, даже если они предложили сотрудничать бесплатно. Фактически, документированный проект сначала прошел несколько начальных итераций. Это часто начинается с 1-3, может быть, 5 парней записывают свои новые идеи и демонстрируют их миру в качестве доказательства концепции. Если идея окажется удачной, тогда «последователи» могут добавить, что они, как правило, начинают просить расширения, новые опции, переводы… На данный момент код все еще является прототипом, обычно с жестко закодированными опциями и сообщениями.

Не все проекты с открытым исходным кодом выходят за рамки этой фазы, только те, которые нарушают «критическую массу», необходимую для привлечения общественного интереса. Более того, один из начинающих разработчиков должен «мыслить масштабно и далеко», планировать расширения и так далее. С таким же успехом он может стать «евангелистом» проекта, а иногда и «менеджером проекта» (иногда это разные люди). Это необходимый шаг для развития проекта - от доказательства концепции до признанной в отрасли реальности.

Даже в этом случае менеджер проекта может не создавать документацию.

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

Что обычно происходит:

1. Сделан краткий вводный документ о том, что это за проект и куда он идет (знаменитая «дорожная карта»).
2. Если возможно, разрабатывается API, который выбирается как «документированный код» поверх основной части кода.
3. В частности, API, а также другой код переформатируются и добавляются специальные комментарии "PHPdoc" / "Javadoc" и т. Д. Они предлагают достойный компромисс между затраченным временем и вознаграждением: даже скромный программист обычно знает, как написать один вкладыш, описывающий его функции, параметры также документируются автоматически, и все привязано к соответствующему коду и, таким образом, они избегают документирования. рассинхронизация "и отставание в развитии.
4. Чаще всего создается форум. Это мощная социальная сеть, в которой конечные пользователи и программисты могут общаться друг с другом (и между своими коллегами, возможно, в подфорумах «только для разработчиков»). Это позволяет многим знаниям постепенно появляться и консолидироваться созданными сообществом (читай: не берут на себя ответственность разработчиков) часто задаваемые вопросы и HOWTO.
5. В действительно больших проектах также создается вики. Я заявляю о «больших проектах», потому что они часто имеют достаточно последователей, чтобы создать вики (разработчик делает), а затем фактически заполнить его за пределами «голых костей» (сообщество делает).

Обзорные документы, которые вы описываете, редки даже для коммерческих проектов. Они требуют дополнительных усилий с небольшой пользой для разработчиков. Также разработчики, как правило, не пишут документацию, если в этом нет особой необходимости. У некоторых проектов есть участники, которые хорошо разбираются в технических вопросах, и в результате имеют хорошую пользовательскую документацию. Документация разработчика, если она существует, вряд ли будет обновлена ​​для отражения изменений кода.

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

Чтобы изменить строку кода, вам нужно ограниченное понимание окружающего кода. Вы никогда не должны понимать всю базу кода, чтобы сделать это. Если у вас есть разумное представление о том, какая функция нарушена, часто можно довольно быстро перемещаться по иерархии каталогов.

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

Для языков, которые предоставляют область видимости, вы можете изменить методы приватной области. В этом случае вам может потребоваться изменить вызывающих абонентов, а также метод или методы рефакторинга. Это требует более широкого, но все же ограниченного понимания базы кода.

См. Мою статью Добавление SHA-2 в tinyca для примера того, как такие изменения могут быть сделаны. У меня крайне ограниченное понимание кода, используемого для генерации интерфейса.

Есть ли такие вещи, и я скучаю по ним? Вещи, которые делают ту же работу, что я описываю?

Существует отличная книга под названием «Архитектура приложений с открытым исходным кодом», в которой подробно описываются различные проекты программного обеспечения с открытым исходным кодом. Тем не менее, я не уверен, что она точно соответствует той роли, которую вы представляете, потому что я считаю, что ее основная аудитория предназначена для разработчиков, которые ищут шаблоны, которым следует следовать при создании своих собственных приложений, а не для новых участников проектов, описанных в книге. (хотя я уверен, что это могло бы быть полезным там).

Потому что программистов с открытым исходным кодом гораздо больше, чем технических писателей с открытым исходным кодом.

Документация требует обслуживания и времени, чтобы идти в ногу со временем. Чем громоздче документация, тем больше она занимает. А документация, которая не синхронизируется с кодом, хуже, чем бесполезна: она вводит в заблуждение и скрывает, а не раскрывает.

Хорошо документированная кодовая база лучше, чем одна менее документированная, но документирование может легко занять столько же времени, сколько прежде всего написание кода. Итак, ваш вопрос: лучше ли иметь хорошо документированную базу кода или базу кода, которая в два раза больше? Стоит ли обновлять документацию всякий раз, когда изменения кода приносят вклад дополнительных разработчиков, которых он может или не может принести?

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

Это не значит, что вещи помимо доставки имеют значение. Документация добавляет ценность проекту, и при достаточно большом проекте стоимость межсоединения при добавлении другого разработчика может быть намного выше, чем при добавлении документатора. И, как уже отмечалось, документация может увеличить инвестиции в проект (облегчая присоединение новых программистов).

Тем не менее, ничто не продается как успех: проект, который не работает или делает что-то интересное, редко привлекает разработчиков.

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

Иногда усложнение делает тех, кто делает задачу лучше. Либо из-за более высокой степени приверженности проекту (проводя часы за часами в изучении архитектуры), либо из-за предвзятого отношения к навыкам (если вы уже являетесь экспертом в смежных технологиях, повышение скорости будет быстрее, поэтому барьер отсутствия такая документация менее важна: таким образом, к команде присоединяется больше экспертов и меньше новичков).

Наконец, по причинам, указанным выше, текущие разработчики, вероятно, будут экспертами в области кода. Написание такой документации не помогает им понять основную часть кода, поскольку они уже обладают знаниями, это только помогает другим разработчикам. Большая часть разработки с открытым исходным кодом основана на том, что разработчик сталкивается с кодом: отсутствие документации, которая уже говорит о том, что разработчик знает, редко чешется.

Помимо дополнительных усилий , некоторые проекты с открытым исходным кодом целенаправленно наносят вред своей документации, чтобы получить фриланс-работу для своих сопровождающих (что-то реализовать или провести тренинги). Мало того, что у них нет обзора кода, но их API и учебные пособия плохие или пропускают много вещей.

Просто назвать одно довольно популярное: bluez. Удачи в поиске хорошего учебника, а не для поиска ближайших устройств.