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

[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

мои пять копеек

[furman76.blogspot.com (from livejournal.com)]

Код - это код, комментарии - это комментарии, документация - это документация. Все нужно, у всего свои задачи и свои читатели. Нужна общая архитектурная диаграмма, которая бы объясняла базовые принципы построения системы, основные блоки и взаимодействие между ними, желательны SoWы для разработки новых фичей, нужны javadocs, нужны паттерны и best practiсes для типовых расширений... Сравнивать архитектурные документы с "трекерами с тикетами" совершенно неверно - это разные виды документации, предназначенные для разных целей. В помойке из нескольких сотен тысяч тикетов можно найти нужную информацию только при том условии, что архитектура системы у тебя в голове. Если ты не видишь общей картины, информация о том, что какую-то строчку кода закомментировали из-за такого-то бага, бессмысленна...