?

Log in

No account? Create an account
November 2016   01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
cartoon

Читай код

Posted on 2009.05.03 at 16:01

Comments:


Gaperton
gaperton at 2009-05-04 16:07 (UTC) (Link)
> Я как начал про Software Architecture Document, так и продолжаю. Можете посмотреть шаблон SAD в RUP'е, или IEEE 1471-2000.

Спасибо, видел. Приведите мне еще в пример 19 и 34 ГОСТ. Я о документации знаю вообще гораздо больше, чем вам кажется.

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

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

Весь опыт индустрии на данный момент показывает, что пИсать против ветра не надо, и рулят вовсе не ваши документы, согласно IEEEEEE-XXX-blah-blah-blah-some-shit, в которых почему-то всегда не смотря ни на какие процессы оказывается балшыт и которые люди избегают даже читать, не то что писать.

1 Если код не в порядке - то вам уже ничего не поможет, никакие поясняющие бумажки, а если он есть, то остальное уже не так существенно. Лучше иметь хорошо структурированный и по делу комментированный "литературный" код и никакой документации, чем спагетти-говнокод, сопровождаемый тонной документации, на практике ему не соответствующей. Этот тезис имеет очевидный и абсолютный приоритет, и это вполне понятно каждому инженеру и вменяемому менеджеру, "нюхавшему порох".
2 Необходимы содержательные комментарии к коммитам в VCS. Они _всегда_ и автоматически актуальны, не требуя ровным счетом никаких затрат на свое поддержание в актуальном состоянии. Данные комментарии - дополняют код, объясняя rationale принятых решений. За несоблюдение данного пункта надо жестко 3,14здить - это очень важный пункт, такой же, как и предыдущий.
- содержательное описания тикетов в базах данных, привязанное к коммитам в SVN. В этом случае элементарным образом по каждой строке кода получается тикет в БД, и наоборот, обеспечивая практичным образом ту самую трассировку требований, работающую в реальной ситуации поддержки, без всяких магических пассов руками, накидывания умняка, и прочего балшыта.
3 Документация, генерирующаяся из исходного кода с комментариями автоматически. Это на практике вообще единственный способ поддержать ее в актуальном состоянии. Этот пункт, как показывает практика, приятен, но при наличии предыдущих пунктов совершенно не критичен.

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

Некоторые пропускают пункт 2 и имеют проблемы - ибо это очень чревато. Многие пропускают пункт 3 - это некритично. Тем, кто пропускает пункт 1 - ничего не поможет.

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

В качестве справочника по API отлично работает пункт 3 - из кода автоматически. Исключение состовляют design principles - это ОЧЕНЬ короткие документы, объясняющие подход к организации некоторых центральных API или фреймворков, если они в системе есть. Их исполнение проверяется на design review. Все.

kurilka at 2009-05-04 17:03 (UTC) (Link)
Спасибо, по-моему это было бы не лишним в отдельный пост вынести.
Сергей Боборыкин
ligwar at 2009-05-05 20:11 (UTC) (Link)

Спасибо!

Спасибо, круто! :))
Я тоже думаю, запись заслуживает отдельного поста! ;)
Previous Entry  Next Entry