Названия функций для лучшей читаемости

Это клише, но остается верным, как никогда ... в программном обеспечении трудно давать названия объектам!

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

Как частый читатель кода (не так ли?), Я знаю, какой из них предпочитаю.

Недавний обмен в нашей команде оказался отличным примером этого. Давайте взглянем.

У нас есть сага, в которой выполняется действие, представляющее обновление записи, которое запускает обновление с несколькими местоположениями в Firebase. Мы храним запись в ее полной форме в корневом узле /articles, а также у нас есть другое место, представляющее эту запись на временной шкале, например. /timelines/articles.

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

У нас есть телефонный код…

return database.ref().update({
  [`articles/${key}`]: article,
  ...buildLocaleReferences({ 
    allLocales: locales, 
    articleLocales, 
    key 
  })
})

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

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

Давайте попробуем переименовать это, чтобы помочь читателю.

return database.ref().update({
  [`articles/${key}`]: article,
  ...timelineReferencesForLocales({ 
    allLocales: locales, 
    articleLocales, 
    key 
  })
})

Хорошо, это начинает выглядеть немного лучше. Тем не менее, мы все еще можем улучшить это.

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

const articleRootReference = { [`articles/${key}`]: article }
const timelineReferences = timelineReferencesForLocales({
  allLocales: locales,
  articleLocales,
  key
})
return database.ref().update({
  ...articleRootReference,
  ...timelineReferences
})

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

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