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

60

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

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

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

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

fiatjaf
источник
7
Вы имеете в виду проектный документ? Я видел редкий проект с описанием каждого пакета, но обычно это уже API.
фрик с трещоткой
14
Почему? Потому что есть немного проектов, чьи сопровождающие хотят инвестировать усилия в написание и поддержание высококачественной документации, и часто они также могут не понимать преимуществ.
Алекс Д
9
Документация может быть устаревшей или неточной по отношению к фактическому поведению. Код не может. Поэтому большинство проектов предпочитают код.
Пол Дрэйпер
5
Также легко недооценить, сколько вы можете узнать о проекте, если вы установите кухонный таймер на 2 часа или около того и просто прочитайте его (tm).
Кос
43
Добро пожаловать в мир, управляемый сообществом: если это не сделано, то это потому, что вы этого не сделали :)
mgarciaisaia

Ответы:

60

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

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

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

Килиан Фот
источник
6
Что ж, похоже, ответ - да: gnunet.org/gnunet-source-overview
fiatjaf
5
Если вы хотите, чтобы это существовало, добровольно напишите это. Весь смысл проектов с открытым исходным кодом состоит в том, что люди могут и должны вносить свой вклад, при условии, что сообщество согласится с тем, что стоит интегрировать.
Кешлам
8
@keshlam - это имеет смысл, если вы уже участвуете в проекте ... но если вы потенциальный участник, который пытается получить общее представление о том, как работает код, вы - худший человек, которого можно написать этот документ ....
Джон Стори
13
@JonStory Ваша точка зрения верна, но на практике я обнаружил, что и обратное тоже иногда верно. В некоторых проектах я заканчивал тем, что писал кучу документации, основанной на заметках, которые я сделал, изучая недокументированную базу кода. Это была лучшая документация, потому что я должен был начать с API, который я мог видеть, а затем копать все глубже и глубже. Разработчики, написавшие код, уже имели в голове модель кода, и поэтому у них было много предположений о том, что кто-то уже знает. Документация кем-то новым для проекта может быть лучшей документацией для кого-то нового в проекте.
Джошуа Тейлор
6
@JonStory: Если вы ввязываетесь в проект, который недостаточно документирован, вам все равно придется начать выяснять это. Внесение заметок в проект помогает сохранить работу следующего человека. (Я не знаю, чтобы кто-либо использовал наличие или отсутствие документов в качестве решающего фактора, следует ли вносить свой вклад.) Простое улучшение комментариев Javadoc (или эквивалентных) может быть ценным способом начать вносить свой вклад. Серьезно, это основной принцип открытого исходного кода: если вы видите что-то, что нужно сделать, делайте это, а не ждите, пока кто-то другой сделает это.
Кешлам
14

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

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

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

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

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

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

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

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

  1. Сделан краткий вводный документ о том, что это за проект и куда он идет (знаменитая «дорожная карта»).
  2. Если возможно, разрабатывается API, который выбирается как «документированный код» поверх основной части кода.
  3. В частности, API, а также другой код переформатируются и добавляются специальные комментарии "PHPdoc" / "Javadoc" и т. Д. Они предлагают достойный компромисс между затраченным временем и вознаграждением: даже скромный программист обычно знает, как написать один вкладыш, описывающий его функции, параметры также документируются автоматически, и все привязано к соответствующему коду и, таким образом, они избегают документирования. рассинхронизация "и отставание в развитии.
  4. Чаще всего создается форум. Это мощная социальная сеть, в которой конечные пользователи и программисты могут общаться друг с другом (и между своими коллегами, возможно, в подфорумах «только для разработчиков»). Это позволяет многим знаниям постепенно появляться и консолидироваться созданными сообществом (читай: не берут на себя ответственность разработчиков) часто задаваемые вопросы и HOWTO.
  5. В действительно больших проектах также создается вики. Я заявляю о «больших проектах», потому что они часто имеют достаточно последователей, чтобы создать вики (разработчик делает), а затем фактически заполнить его за пределами «голых костей» (сообщество делает).
Дарио Фумагалли
источник
2
УХ ТЫ!! мы живем (и работаем) в двух совершенно разных мирах. Где бы вы ни работали в настоящее время, быстро уходите оттуда и найдите компанию (их много), где все будет сделано правильно, потому что это на самом деле экономит ваши деньги. Никогда не позволяйте остроумным менеджерам / ковбойским кодировщикам пытаться сказать вам иначе.
Mawg
6
+1, я согласен почти со всеми вашими пунктами, единственное утверждение, которое я категорически отвергаю, это то, что параметры документируются автоматически . Когда мы думаем об объяснениях, а не просто о синтаксических / типовых ограничениях, ничто не становится «автоматически документированным»; сгенерированный комментарий в стиле Возвращает X. для метода getX не является полезной документацией, это просто заполнитель без какой-либо дополнительной информации.
ИЛИ Mapper
3
@Mawg, предоставляющий хорошую документацию, - это инвестиция, вы теряете время разработчика в обмен на (надеюсь) большее количество участников в будущем и некоторые другие преимущества. Но, как и многие в своем роде, это имеет смысл, только если вы знаете, что есть хороший шанс, что проект будет успешным, а большинство программных проектов проваливаются. Важно осознавать предвзятость выживания, когда вы жалуетесь на отсутствие документации в успешных проектах.
congusbongus
Разве не возможно, что эти проекты провалились, потому что они не документировали? Под документом я подразумеваю план, чтобы вы поняли, а не садились за клавиатуру и стучали. Вот моя оценка жизненного цикла проекта, все цифры +/- 5%. Первоначальный материал (требования и варианты использования, архитектура, детальный дизайн) 50%, кодирование от 10 до 15%, тестирование, остальное. «Если вы не в состоянии планировать, вы планируете потерпеть неудачу»
Mawg
6

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

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

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

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

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

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

BillThor
источник
1
Важным моментом здесь было не утверждать, сколько вам нужно знать о коде, чтобы внести изменения. Конечно, это будет зависеть от многих вещей, но вам никогда не потребуется понимать весь код, ни обзор не даст вам такого понимания, но даже для того, чтобы найти строку кода, которую вы измените, вам нужны определенные знания общая структура проекта.
Пятница,
+1 В open source нет ничего особенного. За более чем 10-летний опыт работы в промышленности я ни разу не видел обзорный документ. Как правило, работодатели ожидают, что первый месяц вашей работы будет иметь нулевую производительность, потому что вы изучаете кодовую базу. «Обзоры» обычно реализуются как вопросы ваших коллег
slebetman
5

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

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

bjmc
источник
это больше похоже на комментарий, см. Как ответить
gnat
4
Я не считаю ваш комментарий конструктивным. Чего, в частности, вам не хватает? Многие из других ответов здесь - это длинное предположение о возможных причинах, по которым разработчики могут не писать обзорную документацию. Я привел конкретный пример хороших обзорных документов.
BJMC
1
Я чувствую, что отсутствует ответ на заданный вопрос: «Почему нет обзоров кода для проектов с открытым исходным кодом?»
комнат
3
Я бы сказал , что это невозможно точно ответить на вопрос , как написано , когда, на самом деле, есть есть код обзоры для некоторых проектов с открытым исходным кодом. Я отредактировал свой ответ, чтобы понять, что я узко отвечаю на запрос примеров, которые пользователь, возможно, пропустил.
BJMC
1
Вопрос, как написано, спрашивает: «Есть ли такие вещи, и я скучаю по ним?» Этот ответ отвечает однозначно, указывая на существующую коллекцию таких обзоров кода. Таким образом, я думаю, что это отличный (и уместный) ответ на вопрос.
Джим Гаррисон
4

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

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

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

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

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

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

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

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

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

Yakk
источник
+1 «документация может легко занять столько времени, сколько написано вначале» - или дольше!
Марко
-1

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

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

BЈовић
источник
8
Независимо от того, сколько примеров вы можете перечислить для плохо документированных проектов с открытым исходным кодом, на мой взгляд, утверждение о том, что они «наносят вред своей документации намеренно», должно быть подтверждено убедительными доказательствами (и даже тогда, вероятно, оно не будет общее утверждение).
ИЛИ Mapper
@ORMapper Давайте начнем с "Bluez - величайшая загадка Linux" . Как единственная библиотека Bluetooth для Linux, мне трудно поверить, что это не документация, потому что это дополнительные усилия. Черт, есть доксиген, и как сложно писать простые уроки?
BЈовић
@ORMapper Тогда есть ядро ​​Linux. Если вам что-то не хватает (например, драйвер ядра), если вашей компании не хватает опыта, вы можете либо нанять кого-то, либо найти фрилансера или компанию, которая сделает это за вас. Таким образом, это с открытым исходным кодом, но это идет с ценой
BЈовић
@ORMapper Тогда есть проект с открытым исходным кодом, с документацией в бумажном формате. Таким образом, вы покупаете книгу, а другой документации нет. Эта документация наносит вред или нет?
BЈовић
2
Что бы это ни стоило, я видел достаточно спекуляций на некачественной документации, чтобы, по крайней мере, задаться вопросом, намеренно ли это. Когда те же самые группы, которые размещают недоделанную документацию в Интернете, более чем рады продать вам книгу или учебный класс, совсем не нужно много цинизма, чтобы прийти к такому выводу.
cHao