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

[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

[recoder]

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

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

[zubian.livejournal.com]

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

[bamsic.livejournal.com]

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

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

[zubian.livejournal.com]

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

[bamsic.livejournal.com]

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

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

[zubian.livejournal.com]

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

[bamsic.livejournal.com]

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