Миф о документации, продолжение
И самое интересное - стоит сказать про "документацию" правду, которую в глубине души и так все знают, - и это обычно провоцирует бурление говн, и поток самых невероятных высказываний.
Давайте посмотрим, почему же люди пишут документы тогда, когда они их действительно пишут, а не рассуждают о том, как бы хорошо было, если бы они были, и как плохо, ( Read more... )
Давайте посмотрим, почему же люди пишут документы тогда, когда они их действительно пишут, а не рассуждают о том, как бы хорошо было, если бы они были, и как плохо, ( Read more... )
А вот документирование через JavaDoc - это откровенная лажа. Разве что JavaDoc будет писать ревьюер, а коммитер будет его проверять.
Reply
Удивительное рядом. Что же им помешает работать? :)
> Code review - практика понятная и в некоторых проектах безусловно необходимая. Но применение её не всегда целесообразно или даже не всегда возможно.
Без кодревью не будет соблюдаться кодстандарт, и код не будет понятным. Чтобы писать для человека, а не для машины, автор должен быть абсолютно уверен, что его код прочтет человек. Сейчас прочтет, не через год.
Побочным эффектом кодревью является то, что у нас как минимум двое людей будут в курсе любого куска кода. Так что эта практика целесообразна всегда.
Про "не все всегда возможно" - я изумлен. Пример, пожалуйста. Что же нам может помешать?
> А вот документирование через JavaDoc - это откровенная лажа. Разве что JavaDoc будет писать ревьюер, а коммитер будет его проверять.
Почему?
Reply
Следование стандартам кодирования у меня происходит практически в автоматически режиме, а над понятностью кода я всегда работаю по собственной инициативе. При этом я готов разобраться практически в произвольном коде на Java, примерно этим я и занимаюсь много лет. Да, иногда приходиться повозиться пару часиков, но это не от того, что ревью не было.
Фатально помешать ревью может отсутствие двух вменяемых программистов в команде. А ещё бывают административные проблемы вроде разных часовых поясов и сложностях в настройке VCS.
С JavaDoc всё довольно просто: not tested - not implemented. И на практике мы обычно имеем первую версию JavaDoc к десятой версии кода, что никакого смысла не имеет. А вот комментарии к коммитам и история изменений - вот это работает.
Reply
И тогда ревьювер, когда к нему придет настоящая задача, не увидит твоего коммита, когда к нему придет задача. После чего он завернет ее тебе обратно.
А если ты делаешь просто "левый" коммит - то когда его заметят (а его заметят, ты же к нему комментарий пишешь, и он шлется в общую ленту) - то тебя на первый раз предупредят, а потом - депремируют.
> или ласково убедить ревьюера, что нужно быстренько проапрувить, потому что так надо.
До первого случая, когда ревьювер вместе с тобой получат люлей. Оба получите выговор с занесением, или депремирование, о чем будут оповещены все сотрудники отдела.
После этого, тебе будет куда сложнее ласково договориться с ревьювером. Причем, с любым из.
Reply
Тем более, что речь идёт о в общем-то санитарных нормах. По-моему, это не то, что должно насаждаться силой.
Reply
Ага. Если по человечески до людей не доходит - то будет именно так.
> А люди не пойдут после таких слов другую работу искать?
Ой, ой, как страшно.
Кому нужен сотрудник, который до такой степени принципиально не хочет следовать простейшему процессу, что готов поменять из-за этого работу, и своим примером подрывает дисциплину и боевой дух всей команды? Тебе нужен? Мне нет.
Пусть ищет, это будет его выбор. И заодно - наглядный урок его коллегам.
> Тем более, что речь идёт о в общем-то санитарных нормах.
Именно.
> По-моему, это не то, что должно насаждаться силой.
Неужели?
Reply
При работе с теми, у кого такая проблема есть, я использую личный пример и доброе слово. И если формально "нет коммита без бага" у меня недавно получилось достаточно просто привить, то качество самих багов и к комментариев к коммитам уже тяжелее поднять до приличного уровня.
Reply
Так и должно быть. Ситуация, о которой мы беседуем - клиническое исключение.
> При работе с теми, у кого такая проблема есть, я использую личный пример и доброе слово.
В ряде ситуаций (редких) доброе слово бывает не худо чем-нибудь весомым подкреплять - для вящей убедительности. Одно другому не мешает.
> И если формально "нет коммита без бага" у меня недавно получилось достаточно просто привить, то качество самих багов и к комментариев к коммитам уже тяжелее поднять до приличного уровня.
Рассылку почтовую после коммита сделай, и принудительно всех на нее подпиши. Поможет. Само привьется, как только люди будут знать, что их коллеги могут прочитать, чем они занимались.
Reply
Если бы я мог, я бы безусловно сделал такую рассылку.
Reply
В чем именно проблема-то? :) У кого-нибудь могут быть принципиальные возражения?
Reply
Reply
Нет, не может. Ревью делается по правилам, а не по мнениям. Ошибка ревью - либо человек багу нашел, либо несоответствие кодстандарту.
Если есть претензии к читабельности - отправляем на ревью ко второму программисту, и смотрим, бьются ли их рекомендации между собой.
Конфликт ревью разрешает тимлид под свою ответственность.
Reply
Reply
Что у нас бывает с некоторыми проектами, когда этот один программист крепко болеет, увольняется, или ему не дай бог падает на голову кирпич?
И главное - что же нам с этим делать, а? Может быть, взять другого программиста, у которого тоже один проект, и попросить их проверять код друг друга?
> И никакого тимлида, который читает код.
Проверка должна быть перекрестной, а не тимлидской. И код тим-лида тоже должен кто-то проверять из его команды - без каких-либо исключений.
> И даже если программиста всё-таки два, то это очень не просто может быть наладить код ревью из-за разных человеческих особенностей.
Это, право слово, очень просто. Достаточно фамилию проверяющего в текст коммитмессаджа писать, и реально наказывать за вопиющие косяки обоих. Сразу всем станет очень просто.
Reply
Никакого тимлида - значит тимлида нет физически. При этом два программиста могут работать в совсем разных компаниях.
Reply
JavaDoc проверяется ревьювером, этого достаточно. Предполагается, что программист до этого протестировал код, прогнал регрессию (если есть), и написал своих тестов (если так принято) - тесты тоже проверяются.
Учитывая, что в JavaDoc пишется "контракт" функции или класса, а не реализация - никакой "дырки" в процессе я не вижу. Ее нет.
Reply
Leave a comment