?

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:


Gaperton
gaperton at 2011-06-19 11:54 (UTC) (Link)
> Во-первых постулируется что писать буду потому не умеют объяснять.

Нет такого утверждения в моем тексте.

> Это может быть не так, часто пишут именно что бы не объяснять 1000 раз ("какие параметры у скрипта и где его файлы.")

Это справочная информация, а не учебная.

> Если довести до такого маразма, это будет мешать работать, когда надо ради исправления опечатки в коменте (и тд. по непрерывному росту важности, опечатка в переменной, неправильный отступ, не очень понятное место кода, ...) работать с Jira/звать ревьювить.

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

А если это делается в рамках и в процессе работы по существующей задаче - то достаточно в комментарии к коммиту это упомянуть.
Пушыстый
_winnie at 2011-06-19 17:31 (UTC) (Link)
> > Во-первых постулируется что писать буду потому не умеют объяснять.
> Нет такого утверждения в моем тексте.
Альтернатива в тексте не рассматривается, только красочно расписана как неправильно когда пишут те, кто не умеют объяснять.

> > Это может быть не так, часто пишут именно что бы не объяснять 1000 раз ("какие параметры у скрипта и где его файлы.")
> Это справочная информация, а не учебная.
Тогда сложность создания и поддержки справочной информации переусложнена (в пример приводятся ISO), а нужность недооценена, и непонятно что такое вообще учебная информация.

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

Кстати, ещё непонятно как исправить баг, который не воспроизводится (напр. racing condition который тестеры пока что не воспроизведли). Если же тестеры для этого не нужны, то можно создать кнопку "сделать коммит и сделать на это таск в Jira". Только это приведёт к тому, что в Jira будет миллионы "багов" про "исправил опечатку" и будет тратится время на её оптимизацию.

Gaperton
gaperton at 2011-06-19 17:41 (UTC) (Link)
>>> Во-первых постулируется что писать буду потому не умеют объяснять.

>> Нет такого утверждения в моем тексте.

> Альтернатива в тексте не рассматривается, только красочно расписана как неправильно когда пишут те, кто не умеют объяснять.

Опять таки, нет ничего подобного в моем тексте.

Люди, не умеющие (и не желающие) читать, что написано, лишаются права комментировать в моем журнале.

http://linorg.ru/how-to-read.html

Ибо объяснять им что-либо бесполезно. Всего доброго.
Previous Entry  Next Entry