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

[gaperton]

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

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

Comments

[yakov_sirotkin]

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

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

[gaperton]

> Но я не согласен, что запреты и наказания будут работать.

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

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

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

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

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

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

Почему?

[yakov_sirotkin]

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

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

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

С JavaDoc всё довольно просто: not tested - not implemented. И на практике мы обычно имеем первую версию JavaDoc к десятой версии кода, что никакого смысла не имеет. А вот комментарии к коммитам и история изменений - вот это работает.

[gaperton]

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

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

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

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

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

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

[aamonster]

Читаю - восприятие "ну и хрень пишет"... Эдак до фразы "И пятое, - у меня действительно хорошая новость, для тех, кто еще не в курсе", начиная с которой хочется сказать "ППКС".

[gaperton]

Эта "хрень" в начале - это были объяснения, из которых логически вытекает, что "новость" именно хорошая :).

"Что" - это не так интересно, как "почему".

[malica_dee]

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

[gaperton]

Это как раз не так важно. Эту ленту все равно никто толком читать не будет, здесь эффект на другом основан.

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

И тот факт, что эти простыни никто не читает - ни разу не меняет дела.

Так вот, здесь тот же эффект используется в мирных целях.

[malica_dee]

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

[gaperton]

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

Это ведь тоже информация типа "справочник". :)

[donz_ru]

Много букв и сомнительных выводов из сомнительных аргументов.
В общем, есть, что ответить, но позже. Вкратце - ты сам говоришь, что мир не идеален и не веришь, что кто-то пишет хорошую документацию, но при этом приводишь пример идеальной разработки, при которой документация практически не нужна. Не находишь диссонанс? Мир действительно не идеален, причем вообще во всех отношениях, начиная от хуевого пива в России, заканчивая космическими программами. И разработка тут не исключение.
За правильную мысль относительно интеграции VCS во баг-трекер и т.д. - плюс стопицот.

[gaperton]

> ты сам говоришь, что мир не идеален и не веришь, что кто-то пишет хорошую документацию

Я про "веру" ничего не писал, извини. Мы об инженерии говорим, а не о религии, у нас все доказать и измерять можно.

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

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

[gaperton]

...почему это не является нормой.

[donz_ru]

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

[zhabodav]

Так все здраво изложено, и ни слова про использование тестов в качестве документации.

[gaperton]

Так раскройте тему в комментариях.

[zhabodav]

Да собственно уже

[gaperton]

Согласен, все верно. Я этот аспект опустил. А зря.