Как читать код

8 принципов, которые стоит запомнить

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

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

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

Все, что вы увидите как читатель — это законченный продукт. И если не провести некоторых раскопок, единственный контекст, с которым вы будете работать — это тот самый код на вашем экране.

1. Учитесь копать

Когда вы впервые знакомитесь с серьезной кодовой базой, возможно, вы не будете чувствовать себя разработчиком. Скорее вы будете себя чувствовать археологом, частным сыщиком, или исследователем религиозных книг. Это вполне нормально, ведь в вашем распоряжении есть несколько инструментов для «раскопок». Если вам повезло, и ваши предшественники использовали контроль версий, это стоит отпраздновать! У вас есть доступ к богатству метаданных, и это очень сильно облегчит вам понимание контекста, в котором создавался код. Далее я исхожу из того, что вы используете Git, но в случае с SVN, все будет примерно так же.

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

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

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

2. Вернитесь в прошлое

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

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

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

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

4. Думайте о комментариях, как о подсказках

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

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

5. Найдите Main

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

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

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

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

6. Обращайте внимание на стиль.

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

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

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

7. Ожидайте встретить мусор

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

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

8. Не отчаивайтесь

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