ReCoder (recoder) wrote,
ReCoder
recoder

  • Mood:

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

Отец 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 Документация, генерирующаяся из исходного кода с комментариями автоматически. Это на практике вообще единственный способ поддержать ее в актуальном состоянии. Этот пункт, как показывает практика, приятен, но при наличии предыдущих пунктов совершенно не критичен.

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

coding management

Tags: coding, management
Subscribe
promo recoder august 1, 12:09 35
Buy for 100 tokens
Не так давно Фейсбук научил меня ещё одной классификации людей, в дополнение к стратегам и тактикам, интерналистам и экстерналистам, и разным морально-политическим приверженцам. Впервые эта классификация описана ещё двадцать лет назад Картером и Сэнджером в книге The Programmer's Stone…
  • Post a new comment

    Error

    default userpic

    Your reply will be screened

    Your IP address will be recorded 

    When you submit the form an invisible reCAPTCHA check will be performed.
    You must follow the Privacy Policy and Google Terms of use.
  • 15 comments