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

[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

[zubian.livejournal.com]

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

[recoder]

Так примерно и получается - пока новичок не начнёт ориентироваться в коде, ничего хорошего он и не напишет. Будет писать или не то, или не там, или дублировать уже существующее, или использовать недекватный API.

Хотя, возможно, имеет смысл корпоративная Wiki-FAQ как аннотация к авто-документации...

[zubian.livejournal.com]

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

[bamsic.livejournal.com]

Вот тут ошибочка!

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

[zubian.livejournal.com]

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

[bamsic.livejournal.com]

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

Если уже знаешь - конечно, много ускоришь изучение.

[zubian.livejournal.com]

Общение в магазине - это еще не язык. И даже если в магазине стоишь - без начальных знаний не поможет по любому. Дело не в ускорении, есть много людей что всю жизнь живут в другой стране - а языка толком не знают, хотя и очень хотят выучить - просто не выходит.
Просто на примере английского легко - он настолько вошёл в нашу жизнь + плюс школа, институт, фильмы, игры компьютерные, если не идиот совсем, то конечно поможет. Фонетика схожа, язык индоевропейский тем не менее и т.д. А вот если русского человека забросить куда нибудь в арабскую страну - тут без вариантов вообще.

[bamsic.livejournal.com]

Тогда уж лучше в страны "тональных" языков. :-)

[gorba.livejournal.com]

Ох, друзья мои.

Даже возражать не буду.

[oshpaz.livejournal.com]

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

[recoder]

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

[oshpaz.livejournal.com]

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

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

[gaperton.livejournal.com]

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

[greshnik.livejournal.com]

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

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

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

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