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

[gaperton]

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

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

Comments

[yakov_sirotkin]

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

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

[malica_dee]

Достаточно одной открытой задачи, и вопрос где брать левый номер - решен. Пока кто-то, кому не наплевать на консистенси, не сверит задачу с кодом.
На практике периодически бывает, что программер находит косяк, который не нашли QA, ленится заводить под него баг и ставит левый номер при коммите фикса.

[gaperton]

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

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

> На практике периодически бывает, что программер находит косяк, который не нашли QA, ленится заводить под него баг и ставит левый номер при коммите фикса.

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

[malica_dee]

Если ревьер из той же породы, то закроет глаза. Человеческий фактор.

[malica_dee]

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

[gaperton]

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

Эффект от такой политики на моральный климат - попрошу объяснить. :) Че-то за 6 лет в CQG я, работая программистом и тимлидом, не заметил отрицательного эффекта именно от этой политики - только положительные.

[malica_dee]

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

У нас предпочитают вместо "прицепа" к тикету, делать отдельный коммит, в котором честно написано
Bug ID: n/a
Desc: typo corrected
Если все капельку серьезнее, чем исправление "p" на "o" - то будет там и ревьюер. Если речь идет о чем-то важном - ну тогда пишем тикет, открываем баг, заказчик должен знать, над чем разработчик трудился.

Что характерно - это облегчает чтение каментов к коммитам, "прицепы" считаются скорее порочной практикой.

[gaperton]

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

А вот дырку в процессе, через которую можно шаловливые ручонки в код запустить - вижу.

[malica_dee]

Собственно зависит от уровня внутренней дисциплины в команде. Если она достаточно высокая, то никто в эту дырку и не полезет.

[gaperton]

"Уровень дисциплины" - это не данность, которая дана свыше. Уровень дисциплины зависит от руководителя.

[malica_dee]

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

[gaperton]

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

[malica_dee]

Смысл исключительно в том, чтобы комит, который содержит косметические изменения был отдельным, и содежал комментарий, который говорит, что это косметическое изменение, коммит, который содержит исправление орфографическую ошибку, был отдельным и содержал информацию о том, что здесь была исправлена орфографическая ошибка и ничего больше. А не так, что меняли алогоритм согласно багу №хххх и исправили орфографические ошибки (в другом модуле) и все это одним комитом, и в каменте (который, как мы помним видно, из среды разработки) видно и про алгоритм, и про орфографию в обоих модулях, где были справления (а высота и ширина окна чсх ограничены).

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

[gaperton]

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

Поэтому - не надо заводить левых задач в трекере.

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

К примеру - знаешь, чем чреваты "косметические" на взгляд некоторых программистов переименования процедур и полей в T-SQL? У нас - из-за таких "безобидных" на первый взгляд изменений, твоих коллег могут поднять ночью телефонным звонком, чтобы они исправили проблемы в загрузке сделок до следующего утра.

[malica_dee]

Ну у нас и нету левых, просто есть возможность баг id поставить n/a. Чтобы не писать "прицепов".

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

[gaperton]

> Ну у нас и нету левых, просто есть возможность баг id поставить n/a. Чтобы не писать "прицепов".

Ага. И обойти при этом code review. "Потому, что оно мешает работать".

Знаем, слышали.