Читай код

[gaperton]

Эту статью я написал по просьбе организаторов специально для сайта конференции software people. Опубликована здесь: http://www.softwarepeople.ru/press/articles/09/

Когда я заступил на работу в компанию CQG в конце 1999 года, у меня уже был, как мне казалось, достаточно

Comments

[skyer]

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

[gaperton]

А это так и есть на самом деле. Так же как и большие усилия на документацию для администраторов свидетельствуют о неудобном и неинтуитивном админском интерфейсе, например. Сдвиг акцента на документацию с основной деятельности - всегда дурно пахнет. Больший объем документации не решает проблем, он их усугубляет, и часто является симптомом. Собственно, я добавил к статье:

"Второй аспект этой философии - понимание того, что код пишется в первую очередь для человека, и только во вторую - для компьютера. Это приводит нас к идеям, близким по духу к literate programming, за которое ратует Кнут."

[runixonline]

US US
Аналогичная ситуация существует и в бизнесе. Чем толще "Кодекс Корпоративного Управления" , тем меньше кто либо понимает, что вообще происходит в корпорации.

[skyer]

Да, это уже примерно получает статус признанной истины.

[zhiraffanjut]

Именно поэтому было очень удобно работать в Together/J, ибо там код и документация были неразделимы Ж-) Жаль что её больше нет.

[gaperton]

Ой, не верю я в эти штуки-дрюки. :) Together у нас помню не пошел - он не умел избирательно скрывать методы и данные классов. А их в центральных классах у нас было, гхм, порядка сотни. Представляешь, как весело это на диаграмме смотрится?

Rational Rose - умеет. В ней реально любую диаграмму нарисовать за пару минут. Я ее использовал для подготовки документов, когда требовалось. Бросил нужные классы, они сами связались стрелками, выделил, вставил в документ, добавил описание проблемы, решения, rationale, и отослал почтой. Документ нужен для design review, и после совещаний идет фтопку.

[zhiraffanjut]

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

> Бросил нужные классы, они сами связались стрелками, выделил, вставил в документ, добавил описание проблемы, решения, rationale, и отослал почтой

Думаю вот эта возможность - ключевая. Быстро окинуть взглядом, понять куда идти (куда надо, а не куда посылают).

В яве ещё возможность была чужой код так разбирать. При подключении декомпилятора было очень хорошо копаться в чужих недрах (например application serverа) и выяснять почему эта сволочь валится Ж-)

[glader]

Извини, я не уловил мысль. Что надо делать, чтобы научиться вот так же быстро открывать нужный файл среди 50 Мб других? То есть как (без документации), получив задание на доработку системы, узнать, какой файл надо править?

[gaperton]

Что надо делать, чтобы научиться вот так же быстро открывать нужный файл среди 50 Мб других

[beskov]

т.е. всё-таки архитектурная документация скорее нужна, чем нет?

и надо делать так, чтобы «лекции по архитектуре» разработчики прослушивали в первый месяц работы компании, а не через полгода?

[gaperton]

т.е. всё-таки архитектурная документация скорее нужна, чем нет?

- Common Design Principles - скорее нужна, чем нет. Это краткое описание "правильных" способов делать в системе разные вещи. Скажем, пользоваться вот такими смартпойнтерами, и для посылки сообщений - вот такими классами.

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

Короче, документы, которые имеет смысл писать - должны быть маленькими.

и надо делать так, чтобы «лекции по архитектуре» разработчики прослушивали в первый месяц работы компании, а не через полгода?

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

[vp]

Тут явно должен быть какой-то разумный компромисс. В другой крайности бурно развивается "синдром генерального конструктора", когда основные идеи находятся у автора в голове, и они настолько сложны для передачи кому-то, либо эта передача оценивается настолько дорого, что контора начинает жить мыслью "Только бы он не помер".
ЗЫ Мой подход в этом деле - это вставлять куски документации прямо в код, в модули, с обильными комментариями. Если делаем, к примеру, парсер протокола, то в коде всегда будут куски примеров протокола с расшифровками и т.п. Я думаю, это подход достаточно оправданный, плюс пишется все ОДНОВРЕМЕННО с кодом (!), плюс ничто никуда не потеряется.

[gaperton]

Это и есть примерно то, о чем я говорю.

Ответ однозначный: или да, или нет наверняка. 100%. Без ва

[dmarsentev]

Вы пишете (резюмирую), что
Документация - это мусор и надо читать код.

Вам belnetmon говорит (резюмирую): "А мы всё-таки
считаем, что документация - это правильно и хорошо,
и поэтому вставляем её прямо код."

Вы на это отвечаете:
"Это и есть примерно то, о чем я говорю."Извините, но вы говорили противоположную вещь

Re: Ответ однозначный: или да, или нет наверняка. 100%. Без

[gaperton]

""Это и есть примерно то, о чем я говорю."

Извините, но вы говорили противоположную вещь.
Вы уж как-нибудь определитесь ;)"

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

"Читая свои комментарии, я думаю: Господи,
какой же добрый, умный, хороший человек так
ласково, подробно и не жёстко всё описал.
И после короткой интеллектуальной паузы:
Господи, так это я так хорошо всё описал.
(Слёзы благодарности к себе.)
Неужели у вас такого не было?"

Было ровно то же самое, да. В чем вы видите противоречие? Комментарии - неотъемлемая часть кода. Даже doxygen-комментарии, по которым генерируется документация - есть неотъемлемая часть кода.

Если вы будете читать что написано, то вы прочтете не только то, что хотите, но и например странное сочетание literate programming в

[b00ter]

Хорошая притча. Надо бы ее студентам рассказывать в обязательном порядке.