Программистское мракобесие

[metaclass]

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

А вот оказывается, что так и делают:
К этому моменту я выкинул все свои диаграммы классов, за ненадобностью – зачем на них смотреть, если они давно уже в голове?

Comments

[raydac.livejournal.com]

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

[metaclass.livejournal.com]

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

[raydac.livejournal.com]

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

[volodymir-k.livejournal.com]

Зависит от уровня CMM, принятого в компании. Иногда бывает, что компания крупная, а работают... на коленке. Но редко.

Начиная с CMM 3, каждый проект ведёт массив проектной документации в инфраструктуре, есть процедуры по поддержанию и т.п.

[volodymir-k.livejournal.com]

Документ такой есть: SAD - software architecture document.

[http://users.livejournal.com/_windwalker_/]

А как же постулат из Peopleware, что максимальный уровень CMMI, в котором ещё интересно (и имеет смысл) работать, это 2 ?

[gaperton.livejournal.com]

Как бы это сказать, одного то, чтобы не писать документации, недостаточно для того, чтобы сделать хороший продукт в течении 10 лет :). И написания документации для этого тоже недостаточно, ибо наличие документации (тем более - в актуальном состоянии) само по себе тут вообще не причем и существенного вклада в успех не дает. Зато способствует созданию и поддержанию иллюзии, что вы делаете все "правильно", у вас _якобы_ все под контролем, и у вас все получится, потому, что уровень CMMI зело большой :).

[gaperton.livejournal.com]

А вообще, всякого рода dоxygen-ы рулят, потому что генерятся из кода. И описания Common Design Principles в виде кратких документов - тоже рулят, хотя бы потому, что их соблюдение может быть проверено на design review, и они редко меняются.

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

[gaperton.livejournal.com]

Культ Карго, в общем, косит наши ряды. Меж тем, практика различных open source проектов, в том числе и крупных, скорее подтверждает вышесказанное, чем иллюстрирует декларации CMMI. Разработка ПО не является строго определенным процессом, наподобие линейки по приготовлению гамбургеров макдональдса, где точность соблюдения "технологии" и процесса гарантирует вам качество результата.

У нас зачастую бывает как раз наоборот. Сам IBM PC появился в результате того, что соответствующую группу в IBM освободили от необходимости следовать внутрикорпоративным процессам, "с целью ускорения разработки". Что уж тут говорить :).

[raydac.livejournal.com]

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

[metaclass.livejournal.com]

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

[gaperton.livejournal.com]

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

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

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

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

[http://users.livejournal.com/zubr_/]

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

Насобачился "точки входа" документировать и краткое содержание (без деталей в какой последовательности внутри всё вызывается).
Полезно "список features" иметь.

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

С удивлением обнаружил, что сам работаю по СММ минимум третьего уровня. Просто по-другому самому неприятно.
+1 к "документировать идею". Причем, подписываюсь, что документирование занимает больше времени с момента как только идея продумана до состояния "готово к кодированию".

[aamonster.livejournal.com]

Дык точки входов и назначение объектов - это самое главное. То, чего обычно больше всего не хватает.

[guamoka.livejournal.com]

Страшнее отсутствия документации только документация, написанная людьми, которые ее обычно не пишут, считая, что все заключено в коде и комментариях. Не зависимо от уровня человека как программиста, выражать мысли в документации как правило умеют сущие единицы. У людей реально сносит башню, и "документация" превращается в презентацию, хай-левел дизайн и спецификацию по классам и методам одновременно, причем, желательно все на одном листе. Люди реально не знают, что же требуется отразить "на бумаге", для каких целей это пишется, кто целевая аудитория и когда следует остановится.
ЗЫ. В этом плане поучительна книга Фаулера УМЛ Дистеллед на фоне фолиантов и справочников от Бутча и Ко:)

кстати

[alll]

Помимо всего прочего поддержание актуальной документации создаёт у начальства:
а) Иллюзию заменяемости исполнителя.
б) Недовольство замедленными темпами разработки.
Результат очевиден. ;)

Re: кстати

[volodymir-k.livejournal.com]

О да, начальство это всегда дедушки-крестьяне с Марса! И по-другому, думаете Вы, и быть не может!

Булшит. Начальство занимается доками не потому, что хочет людей заманать. А потому что иначе всё упадёт до уровня советских минских НИИ.

Re: кстати

[golosptic.livejournal.com]

У кого иллюзию - а у кого и обоснованную уверенность.

[vp.livejournal.com]

А вот, кстати, еще пример разбирательства "по коду". Я постоянно на своей шкуре чувствую, когда за тобой потом изучаю то, что ты написал. И есть две вещи, которые замедляют "читабельность с первого раза" в 10 раз: это грамотно развязанный код с целью исключения зависимостей, когда 5 штук классов с наследованной дополняемой функциональностью, или опосредствованный обмен между классами через посредников (щину). Тут только бумагу в руки и рисовать :) Иначе фиг поймешь.

[metaclass.livejournal.com]

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

[blackyblack.livejournal.com]

Документировать код можно легко и безболезненно. Может быть это ООП так негативно влияет на архитектуру?
В целом же правило такое - чем выше уровень программы (или более обще - чем больше совокупная сложность модуля), тем более развёрнутый должна быть документация. Зависимость практически линейная, за исключением хитрых хаков на низком уровне.

[sergiej.livejournal.com]

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

[golosptic.livejournal.com]

ППКС

[gaperton.livejournal.com]

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

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

1) Завязанность компетенции на единичные ключевые фигуры никак не связана с наличием и отсутствием документации. Вообще. Документация - не единственный и во многих случаях не лучший способ передачи знания. Лучшая защита от такой ситуации - поддержание как минимум двух человек на каждой теме, и налаживание среды для передачи знаний. Например, этому способствуют практики design review, имея передачу знаний своим побочным эффектом.
2) Если пропущен пункт 1, то проблемы будут точно, ибо наличие документации само по себе никак не поможет при уходе ключевых фигур. Во-первых, спагетти-говнокоду не поможет никакая документация. Во-вторых, эта документация никогда на практике не соответствует коду, поэтому она практически бесполезна. Поможет только хорошо написанный, и понятно структурированный, и по делу комментированный код, и соблюдение дисциплины работы с VCS - содержательные комментарии к коммитам критичны. Наличие перечисленного, в свою очередь, также никак не связанно с наличием или отсутствием описательной проектной документации, и определяется наличием coding standard, практики перекрестного code review, и практики design review.

Ваша позиция является следствием убеждения, что факта документирования достаточно для надежной передачи знаний. Это не работает на практике на "живых" проектах, у которых поддержка идет одновременно с разработкой (про что я рассказываю) - документация стремительно устаревает, практически всегда out of date, и кроме того, ее мало кто читает. Кроме того, это просто не главное - в реальности упомянутые факторы связываются с наличием документации исключительно искусственным образом.

pt. 2

[gaperton.livejournal.com]

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

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

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

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

На практике, так все и происходит, и именно поэтому вы НИКОГДА не увидите актуальной документации на живом проекте в развитии и поддержке, если она не генерируется из кода. Касательно документации по уже существующему коду, ее дешевле (и на самом деле, это вообще единственный работающий на практике способ) получать из самого кода автоматически. Для C/C++ используйте doxygen. И это и будет как раз тот самый случай, когда код - лучшая документация, ибо doxygen-документация и есть не более чем специальным образом комментированный код. Просто кому-то приятнее его смотреть в браузере - что на самом деле не принципиально.