Как проекты с открытым исходным кодом могут быть успешными без документации об их дизайне или архитектуре?

11

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

Поэтому я решил прочитать их документацию об их дизайне или архитектуре (например, диаграммы UML), чтобы сначала получить общее представление об организации их кода. Однако, к моему удивлению, я не могу найти никакой архитектурной документации для крупных проектов с открытым исходным кодом, таких как Hibernate, Spring, ASP.NET MVC, Rails и т. Д.

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

TomCaps
источник
3
"самый"? Вы можете подтвердить это конкретной статистикой? Сколько вы читали? Сколько их там? Сколько не хватало соответствующей документации? Если у вас нет цифр, удалите слова типа «большинство» и замените их реальными фактами на основе того, что вы действительно нашли. Кроме того, пожалуйста, пишите с заглавной буквы «Я», когда говорите о себе.
С.Лотт
@ S.Lott Извините за субъективное "большинство". Я новичок в индустрии программного обеспечения. Я пытаюсь найти документы, о которых я слышал во время обучения в колледже (такие как UML Diagram, Flow Chart, Brief Design Doc, Detaled Design Doc и т. Д.) Для упомянутых проектов, как на их веб-сайте проекта, так и в хранилище кода, но без удачи, только для того, чтобы найти руководство пользователя док. Можете ли вы научить меня некоторым распространенным способам поиска в их документах по дизайну / архитектуре?
TomCaps
1
Пожалуйста, удалите "Много". Это так же неправильно, как и большинство. пожалуйста, обновите вопрос, чтобы конкретно перечислить конкретные проекты с открытым исходным кодом, которым конкретно не хватает конкретной документации, которую вы хотите увидеть. Пожалуйста, будьте точными и конкретными. Пожалуйста, не будьте субъективными и расплывчатыми.
С.Лотт
Я подозреваю, что причина, по которой ASP.NET MVC не включает диаграммы UML, заключается в том, что Visual Studio может создавать их из исходного кода.
user16764
5
Вы действуете в ложном предположении, что «предприимчивость» - это хорошо. То, что вы узнали в колледже о дизайне, - это ложь: UML абсолютно не имеет значения. При создании проекта все, что вам нужно, - это общее представление о том, что он должен делать, и желание выбросить его, если вы делаете это неправильно в первый раз. Для существующего проекта обычно достаточно просто просмотреть основной заголовок, чтобы получить хорошее представление о макете проекта.
o11c

Ответы:

10

почему проект с открытым исходным кодом может стать успешным, если у новичка нет архитектурного / дизайнерского документа для чтения?

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

Например, если вы посмотрите на PHP-код инфраструктуры Symfony, вы уже должны знать о внедрении зависимостей, событиях, шаблоне модель / представление / контроллер и т. Д.

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

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

Короче говоря, если вам не хватает каких-либо навыков, которые, как ожидают сопровождающие, вы уже знаете, к тому времени, как вы заглянете в их код, вы, вероятно, будете копаться в материалах, значительно превышающих ваш уровень оплаты. Сначала ознакомьтесь с понятиями - что такое модель MVC? Что такое внедрение зависимостей? И т.д. Затем ныряйте.

Дени де Бернарди
источник
1
Хотя, если вы посмотрите на списки рассылки, ядро ​​Linux будет широко обсуждать архитектуру всякий раз, когда у кого-то возникает проблема или вы хотите что-то изменить. Об этом также написано немало документов, хотя и не в самом дереве исходных текстов ядра.
edA-qa mort-ora-y
17

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

Нил
источник
В моей компании это требование процедуры, согласно которой разработчики должны предоставить детальный проектный документ, прежде чем быть утвержденным, написать любой код в проекте. Является ли эта процедура ненормальной для проекта с открытым исходным кодом?
TomCaps
5
@TomCaps Я думаю , самая главная причина , что так мало проектов FOSS есть обширная документация довольно проста: если ваш писать небольшую программу , чтобы решить , что нужно вам есть, это, вероятно , что с вашим разработчиком , что вы также не нужны документы, вам мы собираемся потратить ваше время на улучшение программы, а не на написание документации, которая, как гарантируют, даже никому не будет полезна (что, если проект никогда не используется никем, кроме разработчика?). Это не лучшая практика, но во многих проектах FOSS не хватает времени для разработчиков.
Джефф Веллинг
5
@TomCaps: эта процедура ненормальная для большинства компаний, которых я знаю ...
Треб
1
Большинство проектов с открытым исходным кодом не являются компаниями. Вы думаете о том, что происходит, когда есть проект, за который мне платят, с крайним сроком и бюджетом. Если у вас есть группа людей, которые пишут для удовлетворения своих потребностей или для развлечения, и у вас нет бюджета или клиента, у вас нет таких вещей.
Элин
1
@ TomCaps - любой, кто пишет программное обеспечение с открытым исходным кодом, может делать именно то, что ему нравится. В некоторых проектах (например, в семействе Apache) есть правила и руководства для каждого, кто делает код, и иногда это включает стандарты документирования и т. Д. Кроме того, я бы поставил под сомнение ценность «детального проектного документа», так как это неизменно приведет вас к физическому замыслу, который (в мой личный опыт) обычно не оптимален. Подробное описание того, «что» должна делать программа, дает разработчику возможность оптимизировать реализацию и применять креативные стратегии к решению.
Джеймс Андерсон
12

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

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

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

MaR
источник
8

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

В основном, написание документации не доставляет удовольствия. И если им не платят за это, кто хочет тратить свое свободное время, занимаясь чем-то неинтересным?

GrandmasterB
источник
В некоторых крупных проектах с открытым исходным кодом (GCC, ядро ​​Linux, Firefox, Qt, ....) большая часть (или значительная часть) их участников оплачивается за работу (полный или неполный рабочий день) над проектом. Таким образом, даже когда им платят за бесплатное программное обеспечение, они не пишут много документации
Василий Старынкевич