?

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:


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

Это ж не так просто дотумкать, что человек, назначенный на новую тему, требует введения в нее.
Тем не менее, этот архитектор не мог дотумкать, что человек полгода будет сидеть писать код на ветер и не дал ему никакой документации. И ученик этого архитектора сейчас пишет рекомендации «чтобы знать, как работает код, надо работать с этим кодом, читай код, читай код, сука!».

«Создать благоприятную среду для распространения знаний» — охеренная рекомендация для статьи и выступления.

Что конкретно делать-то? Тыкать людей носом в код?
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)

Спасибо!

Спасибо, круто! :))
Я тоже думаю, запись заслуживает отдельного поста! ;)
Gaperton
gaperton at 2009-05-04 16:08 (UTC) (Link)

И второе.

> Тем не менее, этот архитектор не мог дотумкать, что человек полгода будет сидеть писать код на ветер и не дал ему никакой документации. И ученик этого архитектора сейчас пишет рекомендации «чтобы знать, как работает код, надо работать с этим кодом, читай код, читай код, сука!».

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

Я вообще тебе это уже объяснял. Я бы рекомендовал тебе немедленно прекратить валять дурака, быть поосторожнее в выражениях, как следует задуматься о том, с какой целью ты мне это сюда написал, и что ты тут вообще делаешь в моем журнале. Интеллектуальный эксгибиционизм и словесный онанизм я у себя терпеть в журнале не собираюсь, как и твои переходы на личности. Если не включишь мозг в положение ON, то я просто отправлю тебя в бан, и все, у меня с этим просто.
Денис Бесков
beskov at 2009-05-04 21:59 (UTC) (Link)

Re: И второе.

Владислав, я вроде не давал повода для перехода на ты и «словесный онанизм».

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

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

Это ж не так просто дотумкать, что человек, назначенный на новую тему, требует введения в нее :).
А додуматься записывать на видео семинары архитектора ещё 5 лет назад что мешало «дотумкать»?

То, что вы хороший разработчик, ещё не означает автоматически, что вы хороший архитектор, менеджер и специалист по коммуникациям.
Gaperton
gaperton at 2009-05-04 22:49 (UTC) (Link)

Re: И второе.

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

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

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

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

Всего доброго.
Previous Entry  Next Entry