О пользе чтения кода

[recoder]

Отец gaperton написал крайне занятную статью "Читай код" о том, что лучшая документация - это хороший код. И в своём посте высказывает ещё много интересных идей (с которыми я однозначно соглашусь):

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

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

То есть как (без документации), получив задание на доработку системы, узнать, какой файл надо править?

- понимать, что в крупном проекте актуальной документации у тебя не будет никогда.
- прослушать лекции о Common Design Principles системы, что поможет ориентироваться в системе "вообще". Это очень сильно экономит время.
- Уметь "читать код", пользоваться режимом "annotate" в системе контроля версий, и владеть reverse enginering - уметь восстанавливать дизайн и мысль автора из кода.
- Знать список "центральных" классов подсистемы, и их предназначение, чтобы с них начать. Это поможет сэкономить время.
- На самом деле, если хорошо умеешь читать код, не надо знать и предыдущего. Это довольно быстро восстанавливается из кода - "центральные" классы стоят обычно в центре графа связности.
- Обязательно проводить design review своих решений у знающих людей.
- Менеджерам - следить, чтобы в компании было как минимум два человека, занимающихся каждой подсистемой.
______________________________
[#] > Неужели промышленная высокопроизводительная система из 50Мб кода, живущая уже 10 лет, например, не стоит создания (и актуализации раз в полгода) архитектурного дока на 100 страниц?
Уже почти двадцать лет. Ответ на вопрос стоит или не стоит - как минимум неочевиден. Человеку, работавшему с крупной системой продолжительное время, это вполне понятно. Эти "архитектурные" документы - они из альтернативной реальности, существующей в головах менеджеров, не из разработки. В лучшем случае ими почти никто не пользуется, и от них мало вреда.

А в нормальной реальности рулят базы данных, а не документы. Например, трекеры с тикетами, и комментарии к коммитам в VCS.

Хотя, описание Common Design Principles, для подобных систем, вероятно, держать имеет смысл. Приравняв их по статусу к coding standard, и трактуя нарушение как ошибку на desgn review.
______________________________
[#] 1 Если код не в порядке - то вам уже ничего не поможет, никакие поясняющие бумажки, а если он есть, то остальное уже не так существенно. Лучше иметь хорошо структурированный и по делу комментированный "литературный" код и никакой документации, чем спагетти-говнокод, сопровождаемый тонной документации, на практике ему не соответствующей. Этот тезис имеет очевидный и абсолютный приоритет, и это вполне понятно каждому инженеру и вменяемому менеджеру, "нюхавшему порох".
2 Необходимы содержательные комментарии к коммитам в VCS. Они всегда и автоматически актуальны, не требуя ровным счетом никаких затрат на свое поддержание в актуальном состоянии. Данные комментарии - дополняют код, объясняя rationale принятых решений. За несоблюдение данного пункта надо жестко 3,14здить - это очень важный пункт, такой же, как и предыдущий. - содержательное описания тикетов в базах данных, привязанное к коммитам в SVN. В этом случае элементарным образом по каждой строке кода получается тикет в БД, и наоборот, обеспечивая практичным образом ту самую трассировку требований, работающую в реальной ситуации поддержки, без всяких магических пассов руками, накидывания умняка, и прочего балшыта.
3 Документация, генерирующаяся из исходного кода с комментариями автоматически. Это на практике вообще единственный способ поддержать ее в актуальном состоянии. Этот пункт, как показывает практика, приятен, но при наличии предыдущих пунктов совершенно не критичен.

Главная мысль такова: если код в порядке и есть умные люди - то документация не нужна. А если нету первого или второго - то документация уже не поможет. Вывод для многих неочевидный.

Comments

[oshpaz.livejournal.com]

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

[recoder]

Суровая правда жизни состоит в том, что да, хорошо когда такой документ существует в актуальном состоянии, но обычно его нет. В лучшем случае он безбожнос устарел и не соответствует текущей картине мира проекта. В худшем — им пожертвовали для уменьшения сроков проекта. Документация — обычно входит в те самые 20%, которые откладывают на потом.

[oshpaz.livejournal.com]

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

Но мне показалось что данный пост не сколько о реалиях жизни, сколько о концепциях подхода к документации. С коими я и не согласился.

[gaperton.livejournal.com]

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