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

[metaclass]

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

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

Comments

[raydac.livejournal.com]

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

[volodymir-k.livejournal.com]

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

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

[volodymir-k.livejournal.com]

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

[metaclass.livejournal.com]

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

[gaperton.livejournal.com]

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

[gaperton.livejournal.com]

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

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

[raydac.livejournal.com]

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

[gaperton.livejournal.com]

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

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

[gaperton.livejournal.com]

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

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

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

[raydac.livejournal.com]

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

[raydac.livejournal.com]

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

[gaperton.livejournal.com]

Запиши идею в коде или комментарии к коммиту. В чем проблема-то? Все равно от нее ничего не останется после пары лет поддержки. Твою изначальную идею изменят еще десять раз, исправляя дефекты и докручивая фичи. А глядя в код, про то, что ты оказывается именно это когда-то описал и задокументировал - просто никто не вспомнит.

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

Это в особенности касается больших проектов. Исходя из опыта.

[gaperton.livejournal.com]

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

Поэтому, этой "правильно" написанной с трудом документации даже в лучшем исходе (продукт успешен) никто не воспользуется. Такова суровая правда жизни. Идти против нее - писать против ветра, ИМХО.

[feorex.livejournal.com]

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

[metaclass.livejournal.com]

Было такое, сказали людям "запрограммируйте", дали простое тестовое задание, но толком не разъяснили. Они вместо того, чтобы переспросить 10 раз, два месяца имитировали работу вчетвером(там работы одному человеку на две недели). Зато у них документация по тому бреду, что они пытались выдать за результат - была в идеале. UML диаграммы, построенные по каким-то шаблонам стандартные наборы документов по проекту, итд итп. Капец короче :)

[raydac.livejournal.com]

ключевое тут то, что документация не была в порядке у того кто давал задание

[metaclass.livejournal.com]

Так и есть. Но я документирую идею только в виде кратких заметок и ровно до тех пор, пока код не придет в production-ready состояние, потому что после того уже обычно документирование будет отнимать слишком много времени и толком ничего не принесет. Или будет отставать от кода сильно.

[metaclass.livejournal.com]

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

[gaperton.livejournal.com]

Ключевое здесь, ИМХО, в том, что документация совершенно не причем :). Не в порядке было само задание, а не документация. Документация никакого самостоятельного value не имеет.

[gaperton.livejournal.com]

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

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

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

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

[raydac.livejournal.com]

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

[gaperton.livejournal.com]

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

Я говорю о коммерчески успешной системе, которая находится в поддержке и развитии. Никакого "лоха" в этом случае нет, давно идут продажи и эксплуатация.

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

Эта "карта" будет выброшена в топку, через некоторое время после переходе системы в эксплуатацию и развитие. Вам действительно не везло с проектами - самое интересное начинается ПОСЛЕ того, как начинается эксплуатация. Только тогда ты и имеешь шанс посмотреть, как обойдутся с "картой".

[raydac.livejournal.com]

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

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

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

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

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

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

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

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