Миф о документации, продолжение
И самое интересное - стоит сказать про "документацию" правду, которую в глубине души и так все знают, - и это обычно провоцирует бурление говн, и поток самых невероятных высказываний.
Давайте посмотрим, почему же люди пишут документы тогда, когда они их действительно пишут, а не рассуждают о том, как бы хорошо было, если бы они были, и как плохо, ( Read more... )
Давайте посмотрим, почему же люди пишут документы тогда, когда они их действительно пишут, а не рассуждают о том, как бы хорошо было, если бы они были, и как плохо, ( Read more... )
> Ну, наверное - «если написать один раз, то это будет лучше, чем объяснять ее двадцать пять раз». Это распространенное заблуждение тех, кто никогда не пробовал писать учебников. И любимая отговорка тех, кто не умеет толково объяснять.
Неверный логический переход. Во-первых постулируется что писать буду потому не умеют объяснять. Это может быть не так, часто пишут именно что бы не объяснять 1000 раз ("какие параметры у скрипта и где его файлы.")
Так же кроме учебников есть "методички", "распечатки", а не только "учебники", и прочие мелочи, которые дают обзор, не ставя целью полный охват.
> за неуказание в них номера задач в трекере и фамилии проверяющего - убивать на месте.
Если довести до такого маразма, это будет мешать работать, когда надо ради исправления опечатки в коменте (и тд. по непрерывному росту важности, опечатка в переменной, неправильный отступ, не очень понятное место кода, ...) работать с Jira/звать ревьювить.
Reply
Нет такого утверждения в моем тексте.
> Это может быть не так, часто пишут именно что бы не объяснять 1000 раз ("какие параметры у скрипта и где его файлы.")
Это справочная информация, а не учебная.
> Если довести до такого маразма, это будет мешать работать, когда надо ради исправления опечатки в коменте (и тд. по непрерывному росту важности, опечатка в переменной, неправильный отступ, не очень понятное место кода, ...) работать с Jira/звать ревьювить.
Регулярно совать руки в код без веской на то причины, просто "переписывая непонятный код", рискуя при этом вызвать ошибку, при этом топая ножкой, и настаивая на праве коммита этой не имеющей ценности для пользователя самодеятельности в транк без ревью - это не есть "работа". Это источник ошибок, и саботаж.
А если это делается в рамках и в процессе работы по существующей задаче - то достаточно в комментарии к коммиту это упомянуть.
Reply
Reply
>> Нет такого утверждения в моем тексте.
> Альтернатива в тексте не рассматривается, только красочно расписана как неправильно когда пишут те, кто не умеют объяснять.
Опять таки, нет ничего подобного в моем тексте.
Люди, не умеющие (и не желающие) читать, что написано, лишаются права комментировать в моем журнале.
http://linorg.ru/how-to-read.html
Ибо объяснять им что-либо бесполезно. Всего доброго.
Reply
(The comment has been removed)
Кстати, ничего не мешает то же самое делать с SVN - там бранчевание дешевое. Казалось бы :). Если медленно - берем в качестве клиента к SVN-у Bazaar, и бранчуемся локально.
Reply
Reply
Reply
Leave a comment