?

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 2011.06.18 at 23:06

Comments:


Яков Сироткин
yakov_sirotkin at 2011-06-18 19:47 (UTC) (Link)
Я в принципе согласен про рабочую документацию. Но я не согласен, что запреты и наказания будут работать. Code review - практика понятная и в некоторых проектах безусловно необходимая. Но применение её не всегда целесообразно или даже не всегда возможно.

А вот документирование через JavaDoc - это откровенная лажа. Разве что JavaDoc будет писать ревьюер, а коммитер будет его проверять.
Gaperton
gaperton at 2011-06-18 19:54 (UTC) (Link)
> Но я не согласен, что запреты и наказания будут работать.

Удивительное рядом. Что же им помешает работать? :)

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

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

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

Про "не все всегда возможно" - я изумлен. Пример, пожалуйста. Что же нам может помешать?

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

Почему?
Яков Сироткин
yakov_sirotkin at 2011-06-18 20:10 (UTC) (Link)
Всегда можно поставить левый номер бага или ласково убедить ревьюера, что нужно быстренько проапрувить, потому что так надо.

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

Фатально помешать ревью может отсутствие двух вменяемых программистов в команде. А ещё бывают административные проблемы вроде разных часовых поясов и сложностях в настройке VCS.

С JavaDoc всё довольно просто: not tested - not implemented. И на практике мы обычно имеем первую версию JavaDoc к десятой версии кода, что никакого смысла не имеет. А вот комментарии к коммитам и история изменений - вот это работает.
Gaperton
gaperton at 2011-06-18 20:18 (UTC) (Link)
> Всегда можно поставить левый номер бага

И тогда ревьювер, когда к нему придет настоящая задача, не увидит твоего коммита, когда к нему придет задача. После чего он завернет ее тебе обратно.

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

> или ласково убедить ревьюера, что нужно быстренько проапрувить, потому что так надо.

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

После этого, тебе будет куда сложнее ласково договориться с ревьювером. Причем, с любым из.
Яков Сироткин
yakov_sirotkin at 2011-06-18 20:44 (UTC) (Link)
Люлей? Депримируют? А люди не пойдут после таких слов другую работу искать?

Тем более, что речь идёт о в общем-то санитарных нормах. По-моему, это не то, что должно насаждаться силой.
Gaperton
gaperton at 2011-06-18 20:51 (UTC) (Link)
> Люлей? Депримируют?

Ага. Если по человечески до людей не доходит - то будет именно так.

> А люди не пойдут после таких слов другую работу искать?

Ой, ой, как страшно.

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

Пусть ищет, это будет его выбор. И заодно - наглядный урок его коллегам.

> Тем более, что речь идёт о в общем-то санитарных нормах.

Именно.

> По-моему, это не то, что должно насаждаться силой.

Неужели?
Gaperton
gaperton at 2011-06-18 20:21 (UTC) (Link)
> Фатально помешать ревью может отсутствие двух вменяемых программистов в команде.

Нет, не может. Ревью делается по правилам, а не по мнениям. Ошибка ревью - либо человек багу нашел, либо несоответствие кодстандарту.

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

Конфликт ревью разрешает тимлид под свою ответственность.
Яков Сироткин
yakov_sirotkin at 2011-06-18 20:31 (UTC) (Link)
На некоторых проектах бывает только один программист. И никакого тимлида, который читает код. И даже если программиста всё-таки два, то это очень не просто может быть наладить код ревью из-за разных человеческих особенностей.
Gaperton
gaperton at 2011-06-18 20:24 (UTC) (Link)
> С JavaDoc всё довольно просто: not tested - not implemented

JavaDoc проверяется ревьювером, этого достаточно. Предполагается, что программист до этого протестировал код, прогнал регрессию (если есть), и написал своих тестов (если так принято) - тесты тоже проверяются.

Учитывая, что в JavaDoc пишется "контракт" функции или класса, а не реализация - никакой "дырки" в процессе я не вижу. Ее нет.
Яков Сироткин
yakov_sirotkin at 2011-06-18 20:47 (UTC) (Link)
А если контракт поменялся, а JavaDoc - нет?
Gaperton
gaperton at 2011-06-18 20:34 (UTC) (Link)
"Всегда можно поставить левый номер бага"

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

А вот можно.
миххон
mihhon at 2011-06-18 20:43 (UTC) (Link)
а вы пробовали сами внедрить все эти правила?
с хуками, связями почты-vcs-документами?

если да, сколько человек в команде и какой размер конторы (если в конторе больше одной программерской команды) ?
malica_dee
malica_dee at 2011-06-18 20:48 (UTC) (Link)
Достаточно одной открытой задачи, и вопрос где брать левый номер - решен. Пока кто-то, кому не наплевать на консистенси, не сверит задачу с кодом.
На практике периодически бывает, что программер находит косяк, который не нашли QA, ленится заводить под него баг и ставит левый номер при коммите фикса.
Яков Сироткин
yakov_sirotkin at 2011-06-18 20:56 (UTC) (Link)
Хук можно повесить, если у тебя есть доступ к человеку, который может администрировать сервер.

И нормальным людям хватает просто автоматической привязки коммитов к багам и почтовой рассылки.
Alexey Fyodorov
23derevo at 2011-06-18 23:49 (UTC) (Link)
> применение её не всегда целесообразно или даже не всегда возможно.

Что-то случаев неприменимости в голову не приходит.

Приведи пример, плиз.
Previous Entry  Next Entry