Совет #1 по ознакомлению с новыми кодовыми базами JavaScript

За годы работы программистом я просмотрел, возможно, сотни кодовых баз. Слишком много, чтобы посчитать точно. Я много мучился с пониманием того, где в большинстве случаев находится значимый код. Обычно просьба подсказать, на что я должен обратить внимание, и указания в тикетах подталкивают меня вперед. Медленно, но уверенно, я буду понимать, что делает код. И вы тоже поймёте. У некоторых людей это получается лучше, а у некоторых — медленно. От этого не должно быть стыдно. В большинстве случаев код сложен. Но я нашёл простой инструмент, который облегчит вам задачу. Он называется code-complexity, и вы можете использовать его следующим
образом:

npx code-complexity . --limit 20 --sort ratio
# Вы можете также использовать --filter '**/*.js', чтобы применить паттерн для фильтрации файлов

Он выведет похожий на этот результат:

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

Сложность и текучесть

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

Что такое Сложность?

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

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

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

Что такое Текучесть?

Текучесть немного сложнее для объяснения. Но давайте начнём с чего-нибудь. Текучий файл — это файл, в котором много изменений. Но что это значит?

В файле происходит много изменений, когда, очевидно, много людей изменяют его. Но как кто-то может это измерить? История git'а говорит нам, как часто файл фиксировался. Так что мы можем быть уверены, что файл, вероятно, будет изменён. Обычно это значит, что файлы такого типа являются основной точкой приложения. Проблема, однако, заключается в том, что часто сюда включаются конфигурационные файлы, но вы можете просто исключить их из анализа.

Чему может научить нас Сложность + Текучесть?

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

Детальная проверка файлов

Моя методика детальной проверки файлов довольно проста. Сначала я просматриваю файл и проверяю, как называются экспортируемые функции. В идеале, я записываю их. Внутренние функции в начале не важны для понимания. Получив представление обо всех экспортируемых функциях, я в первую очередь проверяю, есть ли какие-нибудь unit-тесты. Если у функции есть параметры, то я также стараюсь их записать. С типами TypeScript и Flow становится гораздо проще получить общее представление о структуре.

Губка Боб детально проверяет код

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

Почему не нужно понимать каждую деталь?

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

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

Хорошей идеей для первой задачи будет также организовать парное программирование с другими разработчиками из команды. Обязательно скажите им, что вы хотите больше печатать, а они будут больше в качестве наблюдателя, для того чтобы вы научились самостоятельно ориентироваться в кодовой базе. Благодаря такому онбордингу и простым тикетам, вам не придётся вдаваться в подробности. Детали кода будут обнаружены уже в ходе этапа реализации во время исправления багов или добавления нового функционала. Чем больше тикетов вы сделаете, тем больше подробностей вы узнаете о кодовой базе. Но оглядывайтесь назад на текучесть и сложность, потому что они могут меняться со временем.

Отладка деталей?

Теперь работа над кодовой базой будет связана ещё с одной большой вещью — отладкой. В ходе работы над первыми задачами вы, вероятно, уже научитесь, как запускать приложение локально, как запускать unit, интеграционные и e2e тесты, если они есть. Они становятся жизненно важными, когда вы реализовываете что-то, потому что добавление тестов позволит убедиться, что приложение работает так, как от него ожидается. Зачастую эти тесты охватывают много кода и являются в некотором роде абстрактными. В таких случаях вам нужно научиться отладке кода. Поскольку множество тестов выполняются в среде Node.js, мы быстро рассмотрим, как отлаживать приложения на базе Node.js. Множество инженеров используют console.log для отладки, и он полностью работоспособен в этом плане. Но если вам нужно следовать более крупным структурам кода, я могу порекомендовать использовать подходящий отладчик. JavaScript и TypeScript поддерживают ключевое слово debugger, тем не менее, запустить тесты и приятно работать в них с отладчиком довольно проблематично, потому что внутри Node.js немного сложно создать инструменты разработчика из окна браузера и подключить их к программе. Другим вариантом было бы использовать вашу IDE или редактор для подключения отладчика, который поддерживается в них. Например, Visual Studio Code поддерживает отладку Node.js приложений напрямую в IDE. Гайд об отладке Node.js в VS Code можно найти здесь.

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

Примеры

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

Blitz.js

Blitz.js — это фреймворк, построенный поверх Node.js. Он позиционирует себя как Ruby on Rails для JavaScript/TypeScript. Команда работает над этим фреймворком более года, и было бы интересно посмотреть, где находится их ядро логики.

Первым шагом, конечно, склонируем репозиторий в папку и затем выполним:

npx code-complexity . --limit 20 --sort ratio

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

Мы видим, что здесь важны несколько каталогов:

• packages/cli
• packages/generator
• packages/server
• packages/core

Если мы получим задачу, то, по крайней мере, уже будем знать, где искать соответствующий код. Изначально, я бы попытался разобраться в файлах из packages/core, чтобы понять, что они делают. Затем понять тесты, если они есть, и тогда у вас должно появиться хорошее понимание того, что делает Blitz.

React.js

React.js — это фронтенд фреймворк, который почти каждый веб-разработчик сейчас знает. Чего большинство людей не знает, так это как структурирована кодовая база и какие её основные части. Так что давайте посмотрим на это.

npx code-complexity . --limit 20 --sort ratio

Выполнение команды приведёт к следующему результату:

Здесь мы видим, что два подпакета, наверное, наиболее интересны для понимания:

• packages/react-dom
• packages/react-reconciler

Понимание React Fiber и того, как работает частичный отрисовщик react-dom даст вам хорошее представление об архитектуре React. Приятным моментом в коде React является то, что он отлично документирован комментариями, хотя по началу он всё равно сложен.

Venom — TypeScript клиент для Whatsapp

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

npx code-complexity . --limit 20 --sort ratio

Здесь мы можем увидеть, что есть каталоги, которые имеют важное значение:

• src/lib
• src/api
• src/controllers

Как мы можем видеть, в каталоге src/lib лежат автоматически сгенерированные файлы. В идеале, мы могли бы отфильтровать их, но пока давайте посмотрим на другие файлы.

src/api/layers/sender.layer.ts и src/api/layers/retriever.layer.ts не сложные, но имеют много изменений. Поэтому каждый раз, когда функциональность добавляется или удаляется, затрагиваются эти файлы. Это основные файлы приложения и их понимание даст вам хорошее представление о том, как структурирована кодовая база и на чём вам следует сконцентрироваться.

Откуда взялась эта методика?

Эта методика анализа кодовой базы изначально возникла из книги, которая описывала рефакторинг больших кодовых баз: Software Design X-Rays Адама Торнхилла (Adam Tornhill). Это отличная книга, которая научит вас многому: как структурировать код и какие части стоят рефакторинга. Отличная книга. Я думаю, что каждый программист должен прочитать её в какой-то момент, потому что она поможет взглянуть на кодовую базу с другой стороны. Работая над проектом, люди будут знакомиться с различными частями программного обеспечения и, конечно же, у них будет своя особая "область" кода, где им будет супер комфортно. Является ли этот код хорошим и понятным — это еще один вопрос, на который пытается ответить эта книга.

Software Design X-Rays Адама Торнхилла

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

Другие языки

Утилита code-complexity тесно связана с кодовыми базами на JavaScript и TypeScript. Для других языков, таких как Java, C#, Python и PHP существуют другие инструменты, но есть один общий инструмент, который работает для большинства кодовых баз, это code-maat. Это инструмент, созданный автором книги, упомянутой в прошлой главе.

С его помощью вы можете проанализировать проект и прийти к тем же выводам, которые упоминались в статье.

Заключение

Я надеюсь, вам понравилась эта статья, и ваша жизнь стала немного проще. Вход в новую кодовую базу сложен, и особенно в постоянно меняющимся мире JavaScript за ней трудно поспевать. С инструментами и процессами, представленными в этой статье, вам, возможно, будет проще вписаться в новую кодовую базу. Не стесняйтесь поделиться этой статьёй со своими коллегами, а также расскажите им о методиках, которые вы используете. Большинство моих знакомых разработчиков не знают об анализе текучести и сложности, а ведь это может быть очень полезно для всех. Так что поделитесь этим!