?

Log in

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
Tags: , ,
И самое интересное - стоит сказать про "документацию" правду, которую в глубине души и так все знают, - и это обычно провоцирует бурление говн, и поток самых невероятных высказываний.

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


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

Это, например:
- Какой-нибудь договор, которого надо придерживаться, иначе всем будет больно, и обидно.
- Какой-нибудь важный факт, существование которого не худо бы закрепить, чтобы ссылаться на него в будущем. А иначе, когда и если придет Пиздец - вы никому ничего не докажете. Это, например, факты поставки товара, и выплаты денег по договорам.
- Техническое задание, или приказ, в результате которого кому-то надо что-то сделать, и будет весьма неприятно, если оно не сделано.
- Бумажка с диаграммой классов, определением сетевого протокола, или еще чем нибудь, которую вы пишете, чтобы договориться о том, как будет устроена ваша программа, которую вы собираетесь писать большой группой людей.

Список можно продолжать, но главное, думаю понятно. Функция документа в данном случае не в том, чтобы нести знание, или какую-то новую информацию читателям. Она в том, чтобы один раз удостовериться, что несколько человек понимают какую-то важную вещь одинаково. Эта проблема и решается написанием документа. На документ можно потом ссылаться, но сама проблемная ситуация уникальна, и возникает один раз – так что этот документ не обновляется.

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

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

2) "Справочник". Главная функция данного типа "документа" - это некоторый публичный эталон, с которым разные люди многократно сверяются, в чем и состоит его основная функция - он является эталоном. Надо ли говорить, что такой документ крайне дорог в разработке, и кто попало его править не может? Это, например:

- Всевозможные стандарты. Начиная с IETF RFC, ISO 9001, стандарта языка С, и заканчивая вашим внутрикорпоративным стандартом кодирования и процессом внесения изменений в релиз.
- Законы и разного рода регламенты, начиная с конституции РФ, устава вооруженных сил, и заканчивая утверждением "весь код должен лежать в системе контроля версий на сервере sources".
- Орфографический словарь русского языка.
- Описание публичного API операционной системы, или библиотеки. Некоторые такие API закреплены в стандартах, например – POSIX.

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

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

За первыми двумя пунктами стоят объективные проблемы. Такие документы люди пишут сами, добровольно, и не «потому, что надо», а для того, чтобы решить озвученные проблемы.

Но подождите, мы еще не закончили. Если много разных других документов. Например,

3) Обучающий материал. Все мы любим хорошие учебники, правда? Ну это же здорово, открыл учебник в любое время, а там все мегапонятно и хорошо написано. Основная функция «учебника» - донесение новых знаний до читателя структурированным и системным образом.

Ну, что дает «учебник» читателю – это понятно. А вот какую именно проблему автора решает написание «учебника»? И это самый интересный вопрос, давайте рассмотрим его подробнее.

Ну, наверное - «если написать один раз, то это будет лучше, чем объяснять ее двадцать пять раз». Это распространенное заблуждение тех, кто никогда не пробовал писать учебников. И любимая отговорка тех, кто не умеет толково объяснять.

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

Пишут-ли университетские преподаватели учебники? Безусловно. Пишут-ли они хорошие учебники? Бывает и такое, хотя и реже. Однако, освобождает ли это их от обязанности читать лекции, и вести семинарские занятия?

К.О. нам сообщает, что нет, не освобождает – именно лекции и семинары, подразумевающие личный контакт, являются основой передачи сложных технических знаний, концепций, и высшего образования вообще. Еще К.О. добавляет, что дерьмовые лекторы, не умеющие объяснять, крайне редко бывают в состоянии написать сносный учебник.

То есть, в эволюционно сложившемся процессе высшего образования “учебник” вторичен, и первостепенной роли не играет. Бывает, и бывает часто, что адекватного “учебника” для курса лекций попросту не существует – каждый студент попадал в такую ситуацию.

Почему так? Ну право слово:
1) Лекции эффективнее в плане обучения, так как позволяют получать обратную связь от студентов в реальном времени.
2) В курс лекций куда как проще внести изменения, учтя опыт их предыдущего прочтения, и отразив изменения во взглядах на предмет.
3) На подготовку к курсу лекций уходит куда меньше времени и душевных сил.

Так почему же учебники иногда все-таки пишут? Потому, что книги, в отличии от этой вашей хуйни под названием «документация к коду», которую дай бог прочтет полтора человека, дают известность в широких кругах, почет, и уважуху.

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

Разобрались? Теперь резюмируем, и вернемся к вопросу программной документации. Итак, мы выяснили, что:
- по решаемым проблемам «документы» можно условно разделить на «договор», «справочник», и «учебник», и хоть это и не полный список, но вполне достаточный для наших целей. Например – художественная литература нас сейчас не интересует.
- Документ типа «договор» пишут и читают добровольно все, или многие, ибо иначе придет Пиздец.
- «Договор» нет нужны «поддерживать в актуальном состоянии», ибо это лежит за рамками проблемы, решаемой «договором».
- Основная фишка «справочника» в том, что ему точно можно доверять, и он всегда актуален.
- «Справочники» очень дороги в создании и содержании, и нужна действительно веская причина, чтобы его создавать. Меняется справочник редко.
- Если «справочник» будет создан без веской причины, и не будет актуальным – на него все положат хуй. Кому охота читать справочники, особенно если им нельзя доверять?
- «Учебник» - это то, что все читатели любят читать, а авторы – ненавидят писать. И пишут по своей воле только в случае, если в результате маячит почет и уважуха среди большого количества пацанов, и она им зачем-то нужна.
- «Учебник» - не самый лучший способ передачи знаний (особенно – быстро меняющихся знаний), человечеству известны более эффективные способы.
- «Учебник» не обладает свойствами «справочника», а «справочник» - «учебника».
- «Справочник» это еще более хуевое средство передачи новых знаний, чем «учебник». У него другое предназначение.

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

Я вам говорю - "документация" это неуловимый Джо.

Первое. «Учебников», то есть – документации, доступным языком излагающей устройство вашей системы, у вас не будет никогда. Мысль, что ее может написать нихуя не понимающий в предмете «технический писатель» - как минимум забавна. Примерно, как вера в Деда Мороза, или волшебника на голубом вертолете.

Второе. Если у вас в компании нет людей, способных прочитать лекцию по вопросам архитектуры – вам уже пиздец, и никакие гипотетические «учебники» вас не спасут. А если есть – то никакие «учебники» вам не нужны.

Третье. «Справочником» в нашем случае является исходный текст программы, с комментариями в тексте, и с комментариями к коммитам в системе контроля версий. Для тех, кто не умеет читать код – для практически всех современных языков есть автоматические генераторы «справочников» из кода, вроде JavaDoc, волшебным образом решающие проблему актуальности.

Четвертое. Тексты типа «договор», которые в нашем случае отражают требования, иногда результат проектирования, и пр. – не надо пытаться превращать в документы типа «справочник», и поддерживать актуальными. Они решают совсем другую проблему. Эта идиотская затея провалится просто потому, что это нахуй никому не нужно.

И пятое, - у меня действительно хорошая новость, для тех, кто еще не в курсе. Мы живем в 21 веке. Современные трекеры ошибок и задач, такие, как Redmine и JIRA, чудесно интегрируются с почтой и системой контроля версий. Знаете, что это значит? Я объясню.

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

Во-вторых, если вы упомянете в комментарии к коммиту вашей VCS номер задачи, то изменения в коде также автоматически привяжутся к задаче. Что это вам даст?

А то, что глядя на код (который «справочник») в режиме «annotate» (или «Blame», он иногда по разному называтеся), вы видите слева для каждой строки, каким коммитом она добавлена. Ткнув в коммит, вы видите комментарий, который объясняет, зачем она была добавлена. А еще – в это комментарии вы будете видеть ссылку на описание задачи, в результате которой она была добавлена. А в задаче – вы увидите приложенные документы (если есть) и переписку об требованиях.

И наоборот. Вот так решается в современном мире проблема «рабочей документации».

Именно поэтому, не надо заставлять программистов «документировать». Чтобы все было хорошо, достаточно делать очень простые вещи:
- Донести до программистов простую мысль, что программа пишется в первую очередь для человека, и только во-вторую – для компьютера. Из этого много чего следует, например, то, что у идентификаторов должны быть осмысленные имена, и код должен быть в первую очередь понятным.
- Обязательно вводить практику code review, чтобы код обязательно читался человеком перед коммитом. Не, это не о том, что надо всех увещевать. Достаточно запретить все коммиты, в комментариях к которым не указана фамилия проверяющего. И донести до проверяющего мысль, что он разделяет ответственность за коммит. И – обязательно ввести стандарт оформления кода, который должен проверяться на review.
- Больно пиздить за бессодержательные комментарии к коммитам, за неуказание в них номера задач в трекере и фамилии проверяющего – убивать на месте.
- Как вариант – сделать почтовую рассылку комментариев к коммитам, на которую подписать всех, и настроить VCS-хук, запрещающий коммит без валидного номера задачи в трекере. Тогда кровопролитие будет сведено к минимуму.
- Естественно, завести трекер, интегрировать его с почтой и VCS, и настроить процесс так, чтобы все общение по текущим задачам проходило через трекер.
- Если маниакальное желание документировать не пропало – завести JavaDoc/Doxigen/whatever, и проверять их комментарии на code review.
- Для конченных маньяков документации (случаются и такие) – завести вики, и они успокоятся. Следить за контентом, который они генерят, не обязательно.
- А еще вики можно использовать для информации типа “справочник”, которая реально нужна, но не генерируются автоматом из кода. Нет, это не о диаграмме, а о стандарте оформления кода. Так что польза от вики будет.

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

PS:
Сонный городок в западно-американской степи.
Вдруг из салуна вываливается бухой перец, размахивая револьвером, и кричит:
— Я Неуловимый Джо! Я Неуловимый Джо!
Приезжий ковбой в изумлении спрашивает местного:
— Что, неужели правда?.. Это - Неуловимый Джо?
— А то!
— Почему ж его никто не ловит?!
— Да кому он на хуй нужен...


Comments:


Page 1 of 2
<<[1] [2] >>
Яков Сироткин
yakov_sirotkin at 2011-06-18 19:47 (UTC) (Link)
Я в принципе согласен про рабочую документацию. Но я не согласен, что запреты и наказания будут работать. Code review - практика понятная и в некоторых проектах безусловно необходимая. Но применение её не всегда целесообразно или даже не всегда возможно.

А вот документирование через JavaDoc - это откровенная лажа. Разве что JavaDoc будет писать ревьюер, а коммитер будет его проверять.
Gaperton
gaperton at 2011-06-18 19:54 (UTC) (Link)
> Но я не согласен, что запреты и наказания будут работать.

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

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

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

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

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

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

Почему?
aamonster
aamonster at 2011-06-18 20:05 (UTC) (Link)
Читаю - восприятие "ну и хрень пишет"... Эдак до фразы "И пятое, - у меня действительно хорошая новость, для тех, кто еще не в курсе", начиная с которой хочется сказать "ППКС".
Gaperton
gaperton at 2011-06-18 20:14 (UTC) (Link)
Эта "хрень" в начале - это были объяснения, из которых логически вытекает, что "новость" именно хорошая :).

"Что" - это не так интересно, как "почему".
malica_dee
malica_dee at 2011-06-18 20:42 (UTC) (Link)
Как дополнение - количество людей, которые эти самые каменты к комитам получают, не должно быть большим, пять-семь человек, собственно члены команды, иначе этот такие письма будут восприниматься как спам.
Gaperton
gaperton at 2011-06-18 22:00 (UTC) (Link)
Это как раз не так важно. Эту ленту все равно никто толком читать не будет, здесь эффект на другом основан.

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

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

Так вот, здесь тот же эффект используется в мирных целях.
Кирилл Данилов
donz_ru at 2011-06-18 20:52 (UTC) (Link)
Много букв и сомнительных выводов из сомнительных аргументов.
В общем, есть, что ответить, но позже. Вкратце - ты сам говоришь, что мир не идеален и не веришь, что кто-то пишет хорошую документацию, но при этом приводишь пример идеальной разработки, при которой документация практически не нужна. Не находишь диссонанс? Мир действительно не идеален, причем вообще во всех отношениях, начиная от хуевого пива в России, заканчивая космическими программами. И разработка тут не исключение.
За правильную мысль относительно интеграции VCS во баг-трекер и т.д. - плюс стопицот.
Gaperton
gaperton at 2011-06-18 21:22 (UTC) (Link)
> ты сам говоришь, что мир не идеален и не веришь, что кто-то пишет хорошую документацию

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

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

Нет, не нахожу "диссонанса", ибо в описываемой мной среде работаю с 1999 года. Для тебя это может быть "чудо", или "правильная мысль" - а для меня привычка, и мне реально удивительно, почему это не по. Подобное окружение несложно развернуть в любом месте.
zhabodav
zhabodav at 2011-06-18 21:19 (UTC) (Link)
Так все здраво изложено, и ни слова про использование тестов в качестве документации.
Gaperton
gaperton at 2011-06-18 21:24 (UTC) (Link)
Так раскройте тему в комментариях.
Unshaven and Drunk
rlabs at 2011-06-18 23:27 (UTC) (Link)
честно говоря, немного пугает абсолютизм предлагаемых решений. несколько замечаний:
- проекты бывают разные, и бывают в разных ситуациях. любой процесс "делайте так или будете уволены" работает до тех пор, пока не возникает критических ситуаций.
- code review хорошая практика, но (по моему мнению) вводиться она должна через культуру команды, а не через строгие правила. Программисты - неглупые в большинстве своем люди, и легко находят при необходимости обходы для любых метрик, процесов и запретов.
- Javadoc, как и любая документация, быстро теряет актуальность. Во-первых, его не так просто поддерживать, во-вторых, ревью - не самый приятный процесс, и любой нормальный ревьюер будет смотреть в первую очередь на код. Так что не стоит рассчитывать, что code review еще и актуальность документации поддержит
- про лекции и книжки неплохо сформулировано у Вайнберга в одном из "законов": учебник доступен бОльшему количеству людей ценой потери эффективности. Думаю, студенты примерно к такому же выводу приходят.
- ну и про вики не очень понятно. Я стараюсь записывать в вики такие факты, к которым часто приходится возвращаться (кому-то объяснять или вспоминать самому), при этом не являюсь любителем документации. Контент стоит проверять время от времени, так как он имеет обыкновение устаревать, а на него имеют обыкновение ссылаться.
Alexey Fyodorov
23derevo at 2011-06-19 00:02 (UTC) (Link)
> любой нормальный ревьюер будет смотреть в первую очередь на код. Так что не стоит рассчитывать, что code review еще и актуальность документации поддержит

Категорически не согласен! Нужно просто объяснить програмистам, что "проверяем не только код, но ещё и тесты и доки к методам". И добавить, что за баги в тестах и отсталость документации тоже навешаем люлей.

и тогда всё будет ооок!
pingback_bot
pingback_bot at 2011-06-19 04:18 (UTC) (Link)

Про документацию

User localstorm referenced to your post from Про документацию saying: [...] Часть 2 [...]
Lost In Paradox
localstorm at 2011-06-19 04:55 (UTC) (Link)
Привет, как обычно насладился зарядом здравого смысла.. :)

Есть вопрос, на который бы я хотел узнать твой взгляд, gaperton. Вопрос такой. Какие последствия это влечет для активности, называемой QA?

Другими словами смотри что происходит:

1) Есть первоначальный большой договор, когда люди договорились (а не то пиздец). QA-пипл берут "изделие" и сверяют с тем, что было утверждено в договоре. Ну там ещё какие-нибудь стандартные вещи проверяют типа ввод недопустимых значений, краевые всякие случаи и т.п. Все вроде хорошо.
2) Переходим к этапу сопровождения и поддержки, ну и развития. Большие договоры по реинженирингу системы уже очень редки, слава богу на предыдущем этапе сделали все хорошо. Есть некие тикеты в JIRA на мелкие изменения. Ну там штук по 10 в месяц. Ну некоторые тикеты по-больше, некоторые поменьше. В результате требования к системе как таковые начинают эволюционировать и в каждый момент времени это тот изначальный договор + сумма тикетов которые были приняты к разработке. В итоге, понятное дело, некоторые тикеты меняют исходный договор до неузнаваемости.

Внимание, вопросы:

1) Должны ли они проверять только лишь конкретный чейндж?
2) С чем QA-пипл должны сверяться при тестировании системы? Возможен ли тогда регресс-тестинг и до какой степени?
3) Есть ли практическая возможность найти на рынке QA-инженеров, которые могут держать в голове поведение системы до изменений и проанализировать влияние изменения на систему в целом (учитывая сложности с документацией)? Или это в настоящее время что-то из разряда несбыточных мечт или стоит сумасшедших денег?
Gaperton
gaperton at 2011-06-19 09:32 (UTC) (Link)
Это рабочая ситуация, в результате которой трекер ошибок и доработок начинает содержать актуальную информацию по требованиям.

1) QA проверяет конкретное изменение, плюс к этому, конечно, нужен регрессионный тест ("все остальное не изменилось"). Регрессионный тест может быть автоматизирован.
2) В случае, если регрессионный тест проводится вручную QA, им нужен тест-план, по которому они должны идти. Тест план в этом случае обновляется силами QA. Это достаточно дорогой подход к тестированию - но он практически возможен.
3) "...и проанализировать влияние изменения на систему в целом..." - это в общем случае могут только программисты сделать.

Нормальные QA в природе существуют, но в голове держать тест-план для регрессионной проверки - методологически неправильно, даже если у них феноменальная память. Здесь нужна аккуратность, а человек не робот. Поэтому, нужны чеклисты (контрольные списки) для проверок, чтобы ничего не забыть. Их надо составлять до тестирования, и это, в общем, некий вариант тестплана.
Lost In Paradox
localstorm at 2011-06-19 05:27 (UTC) (Link)
Кстати, вот ещё интересный вопрос. Да, все изложенное о документации соответствует действительности. Вот что тогда интересно:

Вот есть скажем какая-то система. Ну она там жила своей жизнью, предположим есть какая-то документация типа такой:

1) Где развернута система (live, test, preprod окружения)
2) Что в целом делает система (очень вверхнеуровнево)
3) Какие-то контакты пользователей или разработчиков других систем, связанный с нашей.

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

Ну и потом какой-то хрен с горы решает передать эту систему на саппорт и развитие ну скажем в другую компанию.

Окей. В другой компании получают это шикарное наследство и начинают постепенно осваиваться. Делают сперва какие-нибудь мелкие фиксы при почти полном отсутствии опыта с этой системой...

Потом клиент говорит: что-то релизы какие-то с багами у вас. Давайте наймем тестеров. Внимание вопрос: это вообще сработает? Что это должны быть за люди, которые подхватят этот софт, поймут его, разработают процедуры приемки и в итоге _повысят_ качество релизов, а не просто будут просто всем трахать мозг, говоря, что для работы им не хватает того, этого, пятого-десятого и вообще что за хуйня, как мы это тестить должны? Где документация? :))
Unshaven and Drunk
rlabs at 2011-06-19 09:21 (UTC) (Link)
сработает, если а) это будут достаточно опытные тестировщики, а не QA, и б) качество релизов будут поднимать разработчики.
Семен
sim0nsays at 2011-06-19 06:08 (UTC) (Link)
Очень разумно и здорово, спасибо.
Так на практике всегда у меня и бывало, но структуризация и аргументация хорошая. В JavaDoc впрочем все равно не верю.

Эх, было бы на английском - всем на работе бы давал читать.
Alexey Fyodorov
23derevo at 2011-06-19 08:28 (UTC) (Link)
так переведи! Думаю, автор будет не против. Особенно, если ссылку на него поставишь!
vovkodav
vovkodav at 2011-06-19 07:53 (UTC) (Link)
есть еще один тип документации, который я бы поставил особняком, хотя можно и рассматривать в рамках предложенных.. :) рекламно-маркетинговые материалы.
Gaperton
gaperton at 2011-06-19 16:15 (UTC) (Link)
Не, этот тип стоит особняком. Совершенно другой мотив автора при его написании, и, кстати, почти полное отсутствие мотива его читать у читателя :). Прямая противоположность "учебнику".

Из рабочего - можно "презентации" добавить. Тоже особый тип документа - иллюстрация к докладу. Его сговнякать элементарно, впрочем. Если знаешь, что хочешь сказать. А если не знаешь - лучше вместо слайдов рисовать картинки :).
mindfactor at 2011-06-19 08:00 (UTC) (Link)
А ссылку на первую часть дайте, плз.
mindfactor at 2011-06-19 08:08 (UTC) (Link)
в смысле - в тексте записи.

Чтобы через год те, кому я дам эту ссылку, не шарились по всемиу ЖЖ по полдня ;)
Пушыстый
_winnie at 2011-06-19 11:44 (UTC) (Link)


> Ну, наверное - «если написать один раз, то это будет лучше, чем объяснять ее двадцать пять раз». Это распространенное заблуждение тех, кто никогда не пробовал писать учебников. И любимая отговорка тех, кто не умеет толково объяснять.

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


> за неуказание в них номера задач в трекере и фамилии проверяющего – убивать на месте.
Если довести до такого маразма, это будет мешать работать, когда надо ради исправления опечатки в коменте (и тд. по непрерывному росту важности, опечатка в переменной, неправильный отступ, не очень понятное место кода, ...) работать с Jira/звать ревьювить.
Gaperton
gaperton at 2011-06-19 11:54 (UTC) (Link)
> Во-первых постулируется что писать буду потому не умеют объяснять.

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

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

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

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

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

А если это делается в рамках и в процессе работы по существующей задаче - то достаточно в комментарии к коммиту это упомянуть.
melkus
melkus at 2011-06-19 14:00 (UTC) (Link)
>Достаточно запретить все коммиты, в комментариях к которым не указана фамилия проверяющего.

А как технически осуществляется доставка кода проверяющему, его же может быть много? Или просто позвать за свой комп?
Gaperton
gaperton at 2011-06-19 14:26 (UTC) (Link)
Например - через систему контроля версий, привязку коммита к тикету, и переназначение тикета на проверяющего, который перенесет коммит в главную ветку.

Есть и другие варианты с использованием спецсредств, например, Atlassian Crucible.

А можно показать изменения с экрана своего компьютера, и заодно объяснить их - это самое простое.
melkus
melkus at 2011-06-19 14:03 (UTC) (Link)
>Ну и главное. Не брать на работу программистом тех, кто не в состоянии
>понятным образом излагать свою мысль на родном языке. Категорически. Эта
>работа им противопоказана.

Я смотрю у Вас толпа программистов стоит за воротами и все молятся чтобы именно их приняли на работу? Лично я согласен иметь помощника, можно 2 которого буду понимать только я, при условии что они будут хорошими экспертами. Базовыми навыками телепатии владею )
Gaperton
gaperton at 2011-06-19 14:19 (UTC) (Link)
> Я смотрю у Вас толпа программистов стоит за воротами и все молятся чтобы именно их приняли на работу?

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

> Лично я согласен иметь помощника, можно 2 которого буду понимать только я, при условии что они будут хорошими экспертами. Базовыми навыками телепатии владею )

Буду иметь в виду эти ценные для меня сведения . :)
melkus
melkus at 2011-06-19 14:06 (UTC) (Link)
>И самое интересное - стоит сказать про "документацию" правду, которую в
>глубине души и так все знают, - и это обычно провоцирует бурление говн,
>и поток самых невероятных высказываний.

Ну этот пост не далеко ушел по провокационности от первого, всё таки многое спорно или возможно недостаточно детализировано.
Gaperton
gaperton at 2011-06-19 14:30 (UTC) (Link)
Странно, а я в нем ничего провокационного не вижу. Спорное - ну попробуйте поспорить. Если не будете переводить обсуждение на личности - то это вполне безопасно. А если будете - то это очень быстро закончится ;)
(Deleted comment)
Gaperton
gaperton at 2011-06-19 14:31 (UTC) (Link)
Поясните, что в точности вы имеете в виду под обоими видами.
(Deleted comment)
(Deleted comment)
(Deleted comment)
blueher at 2011-06-19 18:13 (UTC) (Link)
Я бы добавил ещё один вид документации - "time capsule" или "письмо себе N+10-летнему" - обычно пишется не при написании кода, а при отладке, когда программист понимает что забыл как работает этот код и сам для себя (для следующей отладки) это описывает. Это не договор (пишется в основном для себя и по факту сделанного) не справочник (не поддерживается в актуальном состоянии) и не учебник (пишется для себя или человека на себя похожего). Это как правило довольно внятная документация (пишется же для себя) без "воды", охватывает только самую суть.
Gaperton
gaperton at 2011-06-19 18:17 (UTC) (Link)
Я такое обычно в комментариях к коду писал. Так оно вернее дойдет. И когда понадобится - будет находится в самом годном для этого месте. А то обидно будет, если послание в будущее отправишь, но забудешь, где почтовый ящик, и в какой момент его надо открыть, верно?

А программный код - это особый вид технической документации. Это исполняемая спецификация.
igorilla
igorilla at 2011-06-20 00:12 (UTC) (Link)
- Донести до программистов простую мысль, что программа пишется в первую очередь для человека, и только во-вторую – для компьютера. Из этого много чего следует, например, то, что у идентификаторов должны быть осмысленные имена, и код должен быть в первую очередь понятным.

32 года тому назад эти идеи было откровением, что, ничего не изменилось на Руси ?
Gaperton
gaperton at 2011-06-20 21:35 (UTC) (Link)
Комменты почитайте. Они сами за себя говорят.
Ласка
wesel at 2011-06-20 08:33 (UTC) (Link)
Комментариев не читала, прошу прощения, если этот вопрос уже задавали. Как реализуется пункт с review при использовании Subversion? Не вижу навскидку вменяемого способа прочитать чужой код до того, как он попадет в репозиторий.
Ласка
wesel at 2011-06-20 09:20 (UTC) (Link)
Прочитала комментарии, вопрос снялся (:
Alexander Belchenko
bialix at 2011-06-20 13:31 (UTC) (Link)
Как насчет описания протоколов общения между отдельными узлами системы? Мы это всегда в носим в вики потому что пользуемся ну почти каждый день, т.е. это типа "договора", но по мере развития системы в протоколы вносятся добавления. В какую категорию тогда относятся наши протоколы? Я думаю, что между "договорами" и "справочниками". На code review проверяется соответствие нового кода протоколу.
Gaperton
gaperton at 2011-06-20 21:32 (UTC) (Link)
Отличный вопрос. Если обобщить- это "внешний интерфейс системы", протокол с контрактом.

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

И это действительно значимый пример. Вы нашли "дырку" в рассуждении. Спасибо.
pingback_bot
pingback_bot at 2011-06-22 09:29 (UTC) (Link)

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

User dr_cha0s referenced to your post from Миф о документации, продолжение saying: [...] по полочкам. Автору отдельное спасибо. Originally posted by at Миф о документации, продолжение [...]
pingback_bot
pingback_bot at 2011-06-22 10:28 (UTC) (Link)

Проектная документация и Scrum

User goldtester referenced to your post from Проектная документация и Scrum saying: [...] ;и "Миф о документации. Продолжение" [...]
eao197.blogspot.com at 2011-06-23 06:52 (UTC) (Link)
Есть еще две причины, по которым люди пишут "учебники"

1. Графомания. Т.е. "писатель пишет не тогда, когда может писать, а тогда, когда не может не писать". Вне зависимости от признания. Захотелось, написал. Явление, конечно, редкое. Однако, имеет место быть. В частности, очень часто можно видеть в технических блогах. Когда человек разобрался с какой-то проблемкой и чиркнул в свой блог пару-тройку заметок о том, что, как и почему заработало.

2. Продвижение собственной разработки. Написал кто-то библиотеку. Для того, чтобы ей захотело воспользоваться чуть больше чем несколько коллег с общего проекта, нужно сделать какое-то описание.
zigel
zigel at 2011-06-23 07:11 (UTC) (Link)
В нашей конторе пришли к этому собственной кровью:
Jira + Fisheye + Subversion.
Проекту, сорцам то есть, уже больше десяти лет, работает третье-четвертое "поколение" программистов. Все сначала воют по поводу отсутствующей или неактуальной доки.
А теперь стату кво:
хук на коммите, привязывающий к номеру задачи или названию модуля (нежелательно, но разрешено), опциональные код-ревью с crucible,
вики, куда добровольно пишутся факи и примеры.
ну так, типа, все и решается.
Previous Entry  Next Entry