Перевод статьи Вильяма Шона «How to Read Code (Eight Things to Remember)».
Разработчиков ПО с совершенно разным уровнем опыта зачастую объединяет одна вещь. Они буквально терпеть не могут читать чужой код. Однако, это очень нужный навык, а для разработчика, начинающего работать с уже созданным кем-то кодом, так и вовсе незаменимый. И если вы посмотрите на это дело с правильной точки зрения, да еще и воспользуетесь подходящими инструментами, то процесс чтения чужого кода может вообще стать не только полезным, но и приятным занятием.
Причина ненависти к чтению чужого кода проста: этот код писали не мы. Я не открою большой секрет, сказав, что в глубине души каждый считает себя лучшим программистом в мире. Буквально никто не может писать код так, как пишем его мы. Связано это с тем, что при создании кода происходит интенсивная умственная деятельность, а пассивное чтение не приводит к такому эффекту, и это разочаровывает.
Чтобы вы увидели код в том виде, в котором он есть, могло понадобиться участие многих людей. В ходе его создания могли быть длительные споры. Он может быть результатом совместной работы. Возможно, целые недели ушли на то, чтобы код стал удовлетворять каким-нибудь незадокументированным требованиям, сведения о которых остались только в памяти разработчиков. И, читая код, вы ни о чем из перечисленного не узнаете.
Вы видите перед собой готовый продукт. И единственный явный контекст это слова у вас на экране. Если, конечно, не углубляться в поиски.
1. Учитесь внедряться
Первый раз погружаясь в развитую кодовую базу, вы можете почувствовать себя не разработчиком, а скорее детективом или археологом. И это прекрасно, поскольку у вас есть целый набор «лопат» для раскопок.
Если вам предстоит работать с кодом, создатели которого пользовались системой контроля версий, то вы настоящий везунчик. У вас есть доступ к богатству метаданных, что позволит вам понять не только код, но и контекст, причем с меньшими усилиями. Для целей этой статьи будем считать, что вы пользуетесь Git, но идеи те же и в случае с SVN.
git blame
Благодаря команде git blame вы можете узнать, кто автор и когда файл изменяли в последний раз. Также можно посмотреть хэш коммита для каждой строки.
Очень важно узнать, кто авторы, и постараться с ними познакомиться. Вам может улыбнуться удача и тогда окажется, что авторов немного и они по-прежнему работают с вами, т. е., вы можете использовать их как источник информации. А вот если удача не улыбнется, то окажется, что авторов было множество, причем их имена вам вообще неизвестны.
Вне зависимости от настроения вашей удачи, попробуйте выяснить, кто активнее всего участвовал в проекте.
Знакомство с автором даст вам возможность обратиться к нему напрямую, если вам встретиться непонятная функция, с которой вы не сможете разобраться самостоятельно.
git log
Команда git log используется для просмотра истории коммитов по всему репозиторию. Она выводит все commit messages. Поэтому, если вам нужно найти что-то определенное, воспользуйтесь конвейером и командой grep. Следующая команда выведет все сообщения, в которых встречается «someFunction», с тремя строками контекста:
git log | grep someFunction -C 3
При использовании флага -p можно просмотреть историю какого-то конкретного файла:
git log -p index.js
Посмотрите, кто вносил самые недавние изменения: так вы будете знать, к кому обращаться за информацией, если что.
2. Обратитесь к прошлому
Вы можете просмотреть любой коммит по своему желанию и запустить его, как если бы это был самый недавний коммит в проекте. Зачем это нужно? Например, чтобы проверить последний коммит, который был перед появлением какого-то трудноотслеживаемого бага, и о котором доподлинно известно, что он хороший. Также подобные запуски разных коммитов подходят для случаев, когда вы заскучали и у вас есть настроение для исторических изысканий.
Если ваш проект хостится на GitHub или в похожей системе, то вам повезло. Вы можете извлечь кучу полезный сведений, просматривая issues, пул-реквесты и ревью кода. Приглядитесь к issues, по которым были самые длинные дискуссии. Они могут оказаться проблемными местами. Когда-нибудь вы на них наткнетесь, а заранее почитав ветку обсуждений, будете уже знать, что с этим делать.
3. Читайте спецификации
Так вы получите больше подробностей. Благодаря чтению юнит-спецификаций вы поймете, что должны делать функции и модули, а также каковы предельные значения для их работы. Чтение интеграционных спецификаций поможет понять, каким должно быть взаимодействие юзера и приложения, и какие рабочие процессы это приложение поддерживает.
4. Воспринимайте комментарии как подсказки
Допустим, вам повстречалась странная функция, а чтение комментария к ней только еще больше все усложнило. Есть вероятность, что этот комментарий уже утратил актуальность.
Программисты склонны не замечать закомментированные строки при просмотре кода, поэтому данный комментарий могли просто пропустить и не отредактировать. Возможно, он поясняет итерацию функции, которой уже давно нет, а никто не обратил внимание на несоответствие.
5. Найдите основное
Убедитесь, что знаете, где код начинает выполняться и как происходит запуск. Обратите внимание на файлы, имеющие к этому отношение, представленные классы и опции конфигурации.
Вероятно, вы будете встречать их по всей кодовой базе. Какие-то из этих модулей скорее всего будут иметь довольно общее назначение, без привязки к остальному коду. Они представляют более мелкие и удобоваримые части функционала, с которыми стоит познакомиться прежде, чем браться за более крупное приложение.
Проверьте этот файл с помощью git blame, посмотрите, что менялось в недавнее время. Отрывок кода, в который вносились последние изменения, может стать зацепкой. С ее помощью вы сумеете определить причины проблем, с которыми команда столкнулась в последние недели. Возможно, была представлена новая библиотека, возможно, дело в попытках настроить библиотеку, которая не работала должным образом, а может, это просто boilerplate code, который нужно постоянно обновлять.
Постарайтесь найти ссылки на эти модули в других файлах, чтобы получить представление, как и каким образом они используются. Так вы сможете понять, как они вписываются в приложение в целом.
6. Стиль написания
Вы изучаете, как устроено это приложение, чтобы в конечном итоге писать код для него, так что обращайте внимание на стиль. Это касается и таких явных вещей как соглашения об именах, пробелах, местоположении скобок, и соглашений о написании кода в целом.
Каков общий уровень абстракции? Если это высокоабстрактный многослойный код, вы должны быть готовы писать такой же.
Достаточно покопавшись в истории, вы, вероятно, найдете конкретную точку во времени, когда кто-то из разработчиков решил абстрагировать кусок кода. Как этот код выглядел раньше и как стал выглядеть после? Старайтесь придерживаться того же соглашения при написании собственного кода.
Как пишут код другие члены команды? Если разработчики предпочитают циклы, а не maps, то вам, вероятно, стоит поступать так же.
Если вы выступаете против какого-либо соглашения, поговорите с командой о возможном изменении соглашений в будущем, но не смешивайте разные стили в одном файле. Чем больше будет похоже, что файл написан одним человеком, тем лучше. Тут важнее проявлять последовательность, чем изобретательность.
7. Ожидайте столкнуться с мусором
Вы можете обнаружить функции, которые никогда не использовались. Да что там – целые файлы. Вам может попасться закомментированный код, к которому годами никто не прикасался (git blame в помощь). Не тормозите и не думайте об этом чересчур долго, а также не бойтесь избавляться от таких вещей.
Если бы этот код был нужен, то кто-нибудь пометил бы его в ревью кода. Удалив его, вы облегчите участь следующего читателя.
8. Не заблудитесь
Имейте в виду все вышеперечисленное и не отчаивайтесь, запутавшись. Не стоит ожидать, что чтение кода будет линейным процессом. Также не стоит надеяться, что поймете его полностью. Обращая внимание на существенные детали и зная, где искать ответы на свои вопросы, вы очень быстро во всем разберетесь.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]
Годно