Почему программисты не любят работать с чужим кодом

Как читать чужой код: 6 правил, которые стоит помнить разработчику

Каждому программисту рано или поздно предстоит разобраться в чужом коде, однако не все это делают правильно. Мы перевели статью разработчика Уильяма Шона и узнали, как читать чужой код так, чтобы понимать его и выносить из этой практики что-то новое.

Вы читаете обновленную и улучшенную версию нашей старой статьи

Почему разработчики не любят разбираться в чужом коде

«Ненавижу читать чужой код», — такую фразу можно часто услышать от программистов. Причина их ненависти в том, чужой код пишут не они. Это не значит, что каждый разработчик страдает манией величия, все гораздо проще: читатель никогда не испытает того потокового состояния, в котором находился программист, когда создавал свой код. Поэтому пассивное чтение иногда бывает скучным.

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

Рано или поздно у разработчика наступает момент, когда ему предстоит читать чужой код. Например, когда программисту нужно изменить или обновить существующий код, провести код-ревью, разобраться в работе программного интерфейса. Для этого нужно знать, как читать и понимать чужой код. Это умение полезно и тем, кому только предстоит освоиться в кодовой базе. Разберемся, на что обратить внимание при чтении чужого кода, чтобы понять его и, возможно, чему-то научиться.

Как правильно читать код

Научитесь проводить «раскопки» в коде

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

Если вы работаете над кодовой базой, в которой разработчики использовали контроль версий, то у вас есть доступ к метаданным. Изучите следующие команды для Git, чтобы узнать, как изменялся код (они подойдут и для SVN):

git blame

С помощью этой команды вы узнаете имя автора кода, дату последних изменений и хэш коммита (зафиксированного изменения в коде) для каждой строки. Так можно найти историю кода и понять, какой именно код был внесен в репозиторий, как это было сделано и по какой причине. Если это возможно, познакомьтесь с авторами кода: они постараются ответить на ваши вопросы.

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

Некоторые модули могут выделяться из остального кода и иметь очень общее назначение. Выполните git blame и посмотрите, какие части основного файла недавно изменяли. Так вы узнаете проблемы, которые решала команда в последнее время. Возможно, разработчики долго пытались наладить библиотеку, которая не слишком хорошо работала. Может, там просто шаблонный код, который нужно регулярно обновлять.

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

git log и git grep

Используйте команду git log , чтобы увидеть историю коммитов по всему репозиторию. Команда git grep поможет вам найти в коммитах конкретный текст, например, название функции someFunction: git log | grep someFunction -C 3 . Последние флаги покажут вам найденные выражения с тремя строками окружающего контекста.

Также git log может показать вам историю отдельного файла. Чтобы ее посмотреть, используйте флаг -p: git log -p index.js . Обращайте внимание на имена авторов коммитов, чтобы знать, кому в будущем адресовать вопросы.

Переключайтесь между коммитами и изучайте историю кода

Вы можете переключиться на любой коммит и запустить проект так, будто этот коммит был последним. Как правило, это делают для того, чтобы выявить сложно отслеживаемую проблему. Также коммиты переключают, чтобы увидеть историю кода.

Если проект хранится на GitHub или подобном сервисе, вы можете узнать много нового, читая пулл-реквесты и код-ревью. Обращайте внимание на тикеты — карточки-задачи для отслеживания работы над багами, внедрения функций. Читайте обсуждения в тикетах: там могут быть «болевые точки», с которыми вы можете столкнуться в будущем, поэтому лучше иметь представление о них заранее.

Читайте спецификации

Specs или спецификации — это новые комментарии к коду. Читайте unit specs, чтобы выяснить предназначение функций, модулей и возможные пограничные случаи (edge-cases), которые они обрабатывают.

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

Воспринимайте комментарии как подсказки

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

Обращайте внимание на стиль написания кода

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

Если вы хорошо провели «раскопки», то нашли момент, когда один из разработчиков решил абстрагировать часть кода. Вспомните, как код выглядел до этого изменения и задумайтесь, что с ним стало после выноса на новый уровень абстракции.

Работая над проектом, посмотрите, какие конструкции используют разработчики из вашей команды. Если они отдают предпочтение циклам, а не функции map , то и вам следует их использовать. Если вам не нравится стиль оформления кода в проекте, обсудите это с командой — это лучше, чем смешивать разные стили в одном файле. Хороший код выглядит так, будто он написан одним человеком.

Избавляйтесь от «мусора» в коде

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

Не падайте духом, если чувствуете, что вы совсем запутались в чужом коде. Изучение кода — это не линейный процесс. Не ждите, что сразу поймете все на 100%. Обращайте внимание на важные детали, проводите «раскопки», чтобы найти ответы на вопросы, и, надеемся, все станет понятнее.

Никогда не останавливайтесь: В программировании говорят, что нужно постоянно учиться даже для того, чтобы просто находиться на месте. Развивайтесь с нами — на Хекслете есть сотни курсов по разработке на разных языках и технологиях

История №936401

Меня недавно спросили, почему программисты ненавидят работать с чужим кодом. Долго думал, как донести до обычного пользователя всю суть пиздеца.
Решил привести небольшую аналогию:

Вот представь, что тебе доверили достроить за другим прорабом лабораторию на острове. Ты приходишь на объект, а там кроме недостроенного здания: огромный вентилятор (размером со здание), большой воздушный шар и комната набитая швабрами. Почесав голову, ты разбираешь этот хлам и доделываешь лабораторию. Сдаешь объект ученым, но через 5 минут они выбегают с криком: "УТЕЧКА ЯДОВИТОГО ГАЗА. ".
— Как так–то, блять! Должно же работать! — в отчаянии кричишь ты и звонишь прошлому прорабу:
— Вася, у нас ядовитый газ потёк! В чем проблема?
— Не знаю, должно было все работать. Что–то в проекте менял?
— Немного, швабры вынес.
— Швабры потолок держали!
— Что. Что, блять, извините.
— Говорю, швабры потолок держали. Над ними цистерны с газом были. Очень тяжелые, пришлось в комнату снизу швабры напихать.
— Ты хотя бы записку на двери повесил бы, что швабры для держания потолка! У нас тут ядовитый газ течет! Что нам делать?
— Включай вентилятор. Он сдует газ с острова.
— Я его, блять, демонтировал сразу же!
— Зачем?
— Зачем ты построил 120 тонный вентилятор? Ты не мог положить ящик блядских ПРОТИВОГАЗОВ?
— Ящик противогазов искать нужно, а вентилятор у меня с прошлого заказа оставался.
— Вася, я убрал твой вентилятор! Мы тут задыхаемся!
— Херли вы тогда там делаете? Садитесь на воздушный шар и уебывайте!

Не судите чужой код строго

Так сложилось что большую часть своей сознательной жизни я программирую на PHP. Наш мозг, воспринимая информацию из любого источника, делает это без отрыва от авторитетности этого источника. Грубо говоря, если вы любите PHP — вы автоматически добавили очков авторитетности автору этой статьи, а если не любите — автоматически отняли. Этот процесс происходит на бессознательном уровне и является по сути призмой восприятия, которая с одной стороны защищает нас от падения в бесконечный анализ информации любой степени авторитетности, но с другой стороны ограничивает нас в поиске новой более актуальной информации. Самое поганое здесь то, что авторитетность источника редко когда проверяется на сознательном уровне (потому что на это нужны время и ресурсы в виде драгоценных калорий), я могу быть с той же долей вероятности разработчиком плюсов, домохозяйкой-кухаркой, водопроводчиком без принцессы или генетически модифицированным котом. Не судите мою статью строго, у меня лапки.

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

Когда мы читаем чужой код, нас могут посещать самые разнообразные эмоции: восхищение, смех, раздражение, разочарование, полное неприятие. Полезно знать о том что проявление любых эмоций в любом контексте — это автоматический ответ низшего (первого) уровня нервной системы, сформированный эволюционным путем, необходимый в первобытной среде. Основная задача такого ответа, в случае «негативной» эмоции — запустить механизм действий «бей или беги» с одной единственной целью — выжить. В нашей текущей офисной среде при анализе чужого кода подобный ответ становится скорее бесполезным и даже вредным, поскольку вы тратите на него драгоценное время и ресурсы, плюс загрязняете свой мозг нейромедиаторами, понижающими вашу сообразительность в угоду скорости реакции. Хорошая новость в том что этот ответ можно перепрограммировать. Можно подавлять негативные эмоциональные реакции, а можно их инвентировать, например, смеяться там где вы раньше злились. Смех, в отличие от злости, выбрасывает в мозг хорошие вкусные полезные нейромедиаторы, доставляющие удовольствие, закрепляющие опыт и мотивирующие на дальнейшую работу.

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

Современные средства разработки позволяют практически на лету преобразовывать чужой код в более понятные и приятные структуры. Функция или переменная плохо названа — ctrl+shift+R и в пару секунд она называется по хорошему. Табуляции вместо пробелов, неудобно, непривычно раскиданы отступы и открывающиеся бракеты в египетском стиле — ctrl+shift+F и форматирование восстановлено! Комментарий избыточен или устарел — ctrl+D и его нет. Если изменить призму восприятия, чтение чужого кода может превратиться в увлекательную интерактивную детективную игру.

Код это всего лишь инструмент. Как бы плохо и ужасно он не был написан, в конкретное время и в конкретном месте он успешно решал конкретную проблему, а значит он уже «оправдан». Что-то изменилось в бизнес-требованиях, что то было не учтено — код поломался или стал не актуален, и это нормально. Код имеет свойство эволюционировать самыми разными путями: и постепенно, обрастая пластами и революционно, переписываясь с нуля. Конечно хорошо, когда программист предвидит будущее и на начальных этапах закладывает в код возможности для дальнейшего его развития. Но эта секира остра с двух сторон, вы можете ошибиться с предсказыванием будущего, будущее может не наступить вовсе, а время и ресурсы будут безвозвратно утеряны. Тут важно понимать код какой степени качества от вас требуется. Если это огромная распределенная система, модули к которой программируют ваши коллеги из самых разных точек земного шара в фирмах слабо связанных с вашей, тогда да, имеет смысл использовать модные паттерны, оборачивать модули в сервис-контейнеры даже там где вы не можете себе представить зачем это нужно. Но если это маленькая локальная CRM для одной фирмы, модули которой зависят друг от друга настолько жестко, что отключение любого модуля по сути ведет к остановке работы всей системы… в этом случае вполне оправданно вызывать чужие методы напрямую, это уменьшит количество классов, облегчит вашу оперативную память и сократит время на отладку проблем. Но вот возникает ситуация когда маленькая локальная CRM превращается в нечто расширяемое, что ваша фирма хочет выложить в открытый доступ и продавать. Бизнес-требования изменились. Стоит ли винить программиста в том что он не предвидел этого?

Стандартизация

Код это всего лишь инструмент, но его создание — это чистое творчество. Любую задачу можно решить бесконечным числом самых разнообразных способов. Некоторые из них более производительны, чем другие — пример объективной оценки. Некоторые из них более читабельны, чем другие — пример субъективной оценки. Даже если вы убедите весь офис в том что какой-то кусок кода не читабелен, все еще останется как минимум один автор, который с вами не согласится. Стандартизация кода направлена на то чтобы преобразовать чистое творчество в как можно более рутинный набор действий для того чтобы другим программистам было проще разбираться в вашем коде. То есть, по сути, чтобы вас можно было заменить другим специалистом, более покладистым и дешевым. А через пару десятков лет так и вовсе искусственным интеллектом. Стоит помнить, что если какой-то стандарт противоречит здравому смыслу, возможно его имеет смысл нарушать в некоторых местах, а то и вовсе отказаться от него или заменить на другой, более подходящий.

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

Особое внимание занимают стандарты, основательно обосновавшиеся в культуре просто потому что они возникли раньше других аналогичных стандартов. Каноничный пример это святая война между раскладками QUERTY и Дво́рака. Вторая, очевидно, лучше, но первая держит удар (остается популярнее) просто за счет критической массы пользователей, не желающих переобучаться по новому.

Аналогичные примеры встречаются сплошь и рядом и в культуре программирования. Стандарт PSR ратует за 4 пробела вместо табуляции, игнорируя очевидный факт: среда разработки большинства PHP-программистов изменилась с консольных редакторов на полноценные IDE, в которых оперировать табуляциями удобнее во многих смыслах: и удалять проще, нажимая Backspace один раз, и настроить можно индивидуальную длину табуляции по вкусу.

Применяя тот или иной стандарт задавайтесь вопросом: кому вы делаете удобнее? Кому неудобнее? Кому станет лучше от правила «именуем имена методов лоуерКамелКейсом»? Очевидно лишь тем, кто привык их так именовать. Всем остальным станет неудобно, им придется адаптироваться, а это потери времени и ресурсов абсолютно на пустом месте, учитывая то что
а) теперь у нас есть волшебные IDE, подсвечивающие разными цветами разные элементы кода,
б) программисты имеют свойство перескакивать с проекта на проект, стандарты кодирования в которых могут различаться.

Лично я при разработке своих проектов использую:

• CamelCase для именования классов и методов
• $CamelCase для именования переменных, содержащих экземпляр объекта
• $snake_case для именования переменных, содержащих простые типы

Умение разбираться в чужом коде

Триггер, вызывающий рвотные порывы у подавляющего большинства программистов (пример субъективной оценки). Вам никогда не казалось странным, что зачастую нам проще переписать весь код с нуля, чем разбираться в чужом? В любой другой отрасли мы действуем иначе: сперва учимся читать, потом — писать; сперва пользоваться (электроприборами, зданиями), затем — их проектировать. Мне кажется все дело в нашем образовании (конкретно в области программирования). Нас учат достигать цели самым прямым и быстрым способом, используя некоторые свеже-приобретенные знания. В результате мы комбинируем их (знания) ровно до тех пор пока «оно» не заработает, немного тестируем и отправляем учителю на модерацию. На мой взгляд было бы неплохо добавить в этот процесс дополнительную ступень, на которой мы сравниваем наш код с мастер-кодом, который хоть и не является идеальным и единственно правильным, но дает альтернативный путь решения, зачастую более оптимальный и читабельный.

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

Чужой код ⁠ ⁠

Меня недавно спросили, почему программисты ненавидят работать с чужим кодом. Долго думал, как донести до обычного пользователя всю суть пиздеца. Решил привести небольшую аналогию:

Вот представь, что тебе доверили достроить за другим прорабом лабораторию на острове. Ты приходишь на объект, а там кроме недостроенного здания: огромный вентилятор (размером со здание), большой воздушный шар и комната набитая швабрами. Почесав голову, ты разбираешь этот хлам и доделываешь лабораторию. Сдаешь объект ученным, но через 5 минут они выбегают с криком: «УТЕЧКА ЯДОВИТОГО ГАЗА. «.

— Как так-то, блять! Должно же работать! — в отчаянии кричишь ты и звонишь прошлому прорабу:

— Вася, у нас ядовитый газ потёк! В чем проблема?

— Не знаю, должно было все работать. Что-то в проекте менял?

— Немного, швабры вынес.

— Швабры потолок держали!

— Что. Что, блять, извините.

— Говорю, швабры потолок держали. Над ними цистерны с газом были. Очень тяжелые, пришлось в комнату снизу швабры напихать.

— Ты хотя бы записку на двери повесил бы, что швабры для держания потолка! У нас тут ядовитый газ течет! Что нам делать?

— Включай вентилятор. Он сдует газ с острова.

— Я его, блять, демонтировал сразу же!

— Зачем ты построил 120 тонный вентилятор? Ты не мог положить ящик блядских ПРОТИВОГАЗОВ?

— Ящик противогазов искать нужно, а вентилятор у меня с прошлого заказа оставался.

— Вася, я убрал твой вентилятор! Мы тут задыхаемся!

— Херли вы тогда там делаете? Садитесь на воздушный шар и уебывайте!

Всё так кроме одного. Прошлому разработчику дозвониться невозможно.

Я не программист, но мне кажется, что работа со своим кодом через год после его написания будет выглядеть примерно так же

Мда. Как сисадмин, не могу не согласиться. В ту же степь — «у нас тут надо срочно добавить на сервер еще функционала». Только серверу уже несколько лет, и любые попытки его тронуть на предмет обновления всегда сопровождались воплем вебмастеров «не трогай, умрет!», потому что он весь облеплен их костылями. А тут надо же, «ну нам же очень надо, сделай как-нибудь».

В итоге проще сделать рядом еще один сервер, свежий и со всем что нужно, и приказать этому стаду долбоебов мигрироваться. ИЧСХ, в 99% случаев, конечно же, окажется что-то, что при попытке переложить его на новую платформу издохнет в корчах, потому что несовместимо с новой платформой.

А на вопрос «ребята, а вы вообще каким местом думали, когда предлагали перепахивать боевой сервер? А если бы я вас послушал, и сделал, а оно бы упало, что бы вы дальше делали?» они неопределенно пожимают плечами и блеют что-то типа «ну, эээ, ну ты бы что-нибудь придумал, правда же?»