На прошлой неделе у меня было время поработать над очисткой кода после запуска приложения Cash App в Великобритании, особенно с учетом того, что мои следующие два проекта ждут окончательной версии. Когда я работал над запуском, я вел общий список вещей, над которыми нужно было работать, например, очистку некоторых регулярных выражений или рефакторинг части моего кода. Я также использовал некоторые TODO's в коде для отслеживания очень конкретных изменений кода, которые, как я знал, я хотел бы вернуться и исправить.
if (country === 'United Kingdom') {
// do this
} else {
// do this
}.
Если вы работаете с любым типом кодовой базы, вы часто будете пытаться придумать разумные способы отслеживания вещей в своем коде, будь то ошибка, которую вы хотите исправить, или какую-то общую очистку кода, которую вам нужно сделать. Есть несколько разных способов сделать это, например, используя стикеры, записную книжку, билеты JIRA, список на вашем компьютере или написанный на доске. TODO комментарий где-нибудь в коде - это очень распространенная практика.
Комментарии TODO в коде чрезвычайно полезны, поскольку их легко искать, и их следует писать именно там, где необходимо выполнить соответствующую работу. В большинстве современных IDE (и некоторых текстовых редакторах) есть вкладка для компиляции и просмотра всех ваших TODO в одном месте. Однако чаще всего об этих TODO забывают, навсегда теряют в кодовой базе. Для этого есть несколько разных причин, самая распространенная из которых - когда вы закончите работу с частью кода, вы вряд ли вернетесь к нему и вместо этого продолжите новую часть вашего проекта. В этом случае TODO устареют и могут потерять актуальность. Другая распространенная причина заключается в том, что к тому времени, когда вы вернетесь к комментарию TODO, вы, возможно, забудете, в чем заключалась цель или ваше TODO.
Когда использовать TODO
В моей команде мы стараемся подготовить наш код перед объединением, чтобы снизить потребность в дополнительных мерах в будущем. Однако время от времени в наш код попадает несколько важных TODO, и это совершенно нормально. Чтобы получить максимальную отдачу от своих TODO, особенно когда вы работаете в команде, полезно установить некоторые рекомендации о том, как и когда их использовать. Хорошее правило, которому следует следовать, - использовать TODO, когда это может быть полезно для будущей оптимизации, но не обязательно для отправки кода. В качестве альтернативы, если мы отправляем код, но знаем, что в будущем произойдут изменения в какой-то другой части инфраструктуры (например, смена сервера), и нам нужно будет сделать обновление, как только это изменение произойдет.
Следуйте формату
Согласуйте формат и начните его использовать. Хороший формат должен включать, как минимум, псевдоним или имя разработчика, добавившего комментарий в код, и достаточно описания, чтобы его было легко понять. Первый TODO ниже не очень полезен, а второй дает дополнительную информацию.
// TODO optimize this function // TODO(aashni): optimize this function
Иногда полезно включать дату в свой комментарий, если ваша команда имеет привычку находить в вашем коде TODO давних времен. Для справки - я нашел несколько TODO в нашей кодовой базе как минимум 3 года назад!
Здоровые описания
TODO настолько полезен, насколько это сопутствующее описание. При написании TODO не предполагайте, что в ближайшие несколько дней вы напишете его для себя. Вместо этого представьте, что вы пишете его для нового разработчика в команде, который прочитает комментарий через год. Достаточно ли информации для разработчика, чтобы понять TODO, не приходя искать вас? Если это простое TODO, например make variable configurable, то достаточно оставить его как встроенный комментарий. Для простоты я добавляю осторожность, чтобы держаться подальше от комментариев типа fix this up или reenable this later. Они не предоставляют следующему разработчику полезную информацию о том, что необходимо сделать.
Сосредоточьтесь на том, чтобы указать, где это уместно, почему код находится в текущем состоянии, чего вы ждете перед его обновлением или что мешает его выполнению. Например, если вы ожидаете изменения сервера перед обновлением кода внешнего интерфейса, вы можете написать waiting on code change in server code that will send the country value to the user profile so that we can use country value instead of guessing from the currency value. Это может занять довольно много времени, и никто реально не станет читать много комментариев, если они все очень длинные.
Вместо этого вы можете использовать комбинацию заявки JIRA и комментария TODO. Здесь мы использовали бы waiting on http://link.to/jira/ticker to use country code value. В заявке JIRA должно быть объяснение изменений на стороне сервера, которые должны произойти, а также в идеале ссылка или комментарий об изменениях, связанных с вашим TODO. Это сложная балансирующая игра, заключающаяся в предоставлении только необходимой информации.
Часто сканировать TODO
Сделайте это командной привычкой и, возможно, даже одной из целей вашей команды, чтобы сканировать вашу кодовую базу каждые пару месяцев специально для выявления существующих TODO, если они все еще актуальны, нуждаются в обновлении или могут быть удалены. Если у вас есть новый человек, присоединяющийся к команде, может быть даже хорошей идеей позволить новому человеку просканировать и исправить некоторые из более простых TODO. Обратите внимание, что я строго говорю об использовании этого метода для ознакомления вашего нового члена команды с базой кода - не используйте это как возможность побудить нового члена команды очистить ваш код.
Другие комментарии, подобные TODO
TODO - это только один из типов комментариев, которые вы можете найти в кодовой базе. Есть еще несколько распространенных:
TODO - изменение, которое необходимо внести в будущем, но не обязательно для отправки продукта. Обычно это очистка кода или рефакторинг кода BUG - приведенный ниже код содержит ошибку HACK - приведенный ниже код является временным решением существующей проблемы FIXME - приведенный ниже код не работает по назначению и требует исправления.
Все они звучат похоже, но имеют небольшие различия. Вы должны использовать одни и те же решения, отмечая того, кто написал комментарий, и быть достаточно информативными для всех.
Как вы используете комментарии TODO в своей кодовой базе? Есть ли еще какие-нибудь советы, которыми вы хотели бы поделиться?
Изначально опубликовано в Прогулках Аашни.
