Миф о документации, продолжение

[gaperton]

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

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

Comments

[yakov_sirotkin]

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

А вот документирование через JavaDoc - это откровенная лажа. Разве что JavaDoc будет писать ревьюер, а коммитер будет его проверять.

[yakov_sirotkin]

А если контракт поменялся, а JavaDoc - нет?

[gaperton]

Ревьювер должен проверить. Он разделяет ответственность за коммит - забыл?

Впрочем, я не сторонник этих тулов, ИМХО они мало чего добавляют к коду. Потому и написал в соответствующем пункте - "для маньяков".

Но если есть желание обеспечить их актуальность - это можно сделать.

[gaperton]

"Всегда можно поставить левый номер бага"

И кроме того, тебе известно, что в случае с JIRA и SVN можно повесить не просто тупой пре-коммит-хук, а хук, который требует наличия указанной задачи в JIRA в определенном состоянии? :) Скажем, в статусе "В работе", и при этом она должна быть назначена именно на тебя?

А вот можно.

[mihhon]

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

если да, сколько человек в команде и какой размер конторы (если в конторе больше одной программерской команды) ?

[gaperton]

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

Конечно. У нас в Финаме все работает именно так. Это гораздо проще, чем бегать за людьми, и проверять соблюдение процесса, не так ли?

И в CQG, где я работал первую половину нулевых, все работало примерно так.

> если да, сколько человек в команде и какой размер конторы (если в конторе больше одной программерской команды) ?

Точно не считал - но где-то под сотню. Пока не все из них охвачены новым тулчейном и процессом, но мы в самом начале. :)

В CQG сейчас две сотни.

[gaperton]

Могу описать, как я это сделал. В общем, все достаточно просто - в основе JIRA + SVN + WebSVN, никаких хитростей. Делается прямолинейно, без программирования, никакого хайтека.

[mihhon]

да, наверно это не так и сложно сделать технически

сложнее организационно

для небольшой компании это не так уж и нужно

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

а в софтверной конторе (у брокера, по-большому, весь бизнес софтом делается) на 100-200 человек, где решение принимается 2-5-10 ключевыми людьми, которые тесно сотрудничают, это возможно

[gaperton]

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

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

Вопрос процессов уровня компании, и технической политики - это вопрос руководителя R&D департамента. "Митинги о целесообразности" :).

[mihhon]

большая компания - это большая бюрократическая машина, мотивация частей которой не совпадает с интересами компании :)

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

Вопрос процессов уровня компании, и технической политики - это вопрос кому достанется больше власти и откатов :)

[gaperton]

Ну если все так - то конечно все погрязнет в митингах :).

[mihhon]

Впрочем, в больших компаниях и так есть jira, svn и почта. И без хуков весь процесс воспроизводится, даже и не думал, что это называется процессом документации:) : blame->log->source,поиск в email,поиск в instant messenger,поиск человека. Документацию типа "класс X далает Y" никто не пишет. А спецификации либо отсутствуют, либо оставляют желать лучшего.

[gaperton]

Оно не называется процессом документации.

Результат этого решает те же проблемы, которые не решает документация, но по чьему-то мнению должна.

Весь фокус в обязательности ссылки на задачу или ошибку в трекере. Это ключевое. Тогда не надо будет делать "поиск по e-mail".

[ext_483008]

> Какие еще "митинги о целесообразности внедрения"? :) Принципиальные вопросыь , относящиеся к процессу разработки, решаются руководителем соответствующего уровня, а не "митингами". :) Каждый должен свою работу делать.

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

[gaperton]

"Стоимость внесения изменений". Maintainability. Это - показатель, на который влияют обсуждаемые здесь вещи.

Он аукнется "когда нибудь, и может быть". Посему - не принимается во внимание деревянным менеджментом.

[kholodova]

А опишите, очень интересно.