9 Рекомендаций по Созданию Выразительных Имен

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

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

Не Включайте Тип, Если Он Не Проясняет Намерение

Тип может быть чем угодно — от программного типа (string, int, decimal) до группировки обязанностей (Util, Helper, Validator, Event и т.д.). Часто это классификация, которая не выражает намерение.

Рассмотрим пример: Имя StringHelper не выражает многого. String — это системный тип, а Helper расплывчато, StringHelper говорит больше о “как”, чем о намерении. Если вместо этого мы изменим имя на DisplayNameFormatter, мы получим более ясную картину намерения. DisplayName очень конкретно, а Formatter выражает результат. Formatter может быть или не быть типом, но это не важно, потому что он выражает намерение.

Всегда есть исключения; например, в ASP.Net MVC контроллеры должны заканчиваться на “Controller”, иначе приложение не функционирует. Используя парадигмы, такие как Domain Driven Design (DDD), имена вроде “Services”, “Repository”, “ValueType” и “Model” имеют значение в DDD и выражают ответственность.

Например, UserRepository подразумевает, что пользовательские данные извлекаются и сохраняются в хранилище данных.

Избегайте Метафор

Метафоры культурно обусловлены, и инженеры из других культур могут не понять намерение.

Распространенные метафоры в Соединенных Штатах:

• Beating a dead horse (избивать мертвую лошадь)
• Chicken or the egg (курица или яйцо)
• Elephant in the room (слон в комнате)

Распространенные метафоры в Новой Зеландии:

• Spit the dummy (выплюнуть соску)
• Knackered (измотанный)
• Hard yakka (тяжелая работа)

Используйте Глаголы

Стив Йегге написал (очень длинный) пост в блоге об использовании глаголов вместо существительных.

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

Например, UserAuthentication*(существительное).AuthenticateUser(действие/глагол)* выражает действие проверки учетных данных пользователя.

Будьте Описательными

Будьте описательными, чем больше деталей, тем лучше — выражайте ответственность в имени.

Спросите себя, что одно делает хорошо этот класс или функция?

Если у вас возникают трудности с поиском имени, класс или функция могут иметь более одной ответственности и, таким образом, нарушать Принцип Единственной Ответственности.

Не Полагайтесь на Комментарии для Выражения Намерения

Комментарии — отличный способ предоставить дополнительный контекст к коду, но не полагайтесь на комментарии. Имена классов и методов должны говорить сами за себя.

В “Рефакторинг: Улучшение Дизайна Существующего Кода” Мартина Фаулера, Кента Бека, Джона Бранта, Уильяма Опдайка и Дона Робертса:

… комментарии часто используются как дезодорант. Удивительно, как часто вы смотрите на густо прокомментированный код и замечаете, что комментарии там потому, что код плохой.

Еще одна замечательная цитата от авторов “Рефакторинга”:

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

Много раз, когда код рефакторится и инкапсулируется в метод, вы найдете другие места, где можно использовать новый метод, места, которые вы никогда не предполагали использовать для нового метода.

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

Вот пример включения комментария в имя.

С комментариями:

// without tracking
var user = GetUserByUserId(userId);

Отрефакторено для включения комментария в имя метода:

var userWithOutTracking = GetUserByUserIdWithoutTracking(userId);

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

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

Воздерживайтесь от Использования Имен с Двусмысленным Значением

Избегайте имен с двусмысленными значениями. Значение двусмысленных имен меняется от проекта к проекту, что затрудняет понимание намерения для нового инженера.

Вот список распространенных двусмысленных имен:

• Helper
• Input
• Item
• Logic
• Manager
• Minder
• Moniker
• Nanny
• Overseer
• Processor
• Shepherd
• Supervisor
• Thingy
• Utility
• Widget

Используйте Тот Же Язык, Что и Бизнес-Домен

Используйте ту же терминологию в коде, что и в бизнес-домене. Это позволяет инженерам и экспертам предметной области (SME) легко обмениваться идеями, потому что они разделяют один словарь. Когда нет общего словаря, происходит перевод, который неизбежно приводит к недопониманию.

В одном проекте, над которым я работал, бизнес начал с “Pupil” (ученик), а затем переключился на “Student” (студент). Инженеры-программисты никогда не обновляли программное обеспечение, чтобы отразить изменение в терминологии. Когда новые инженеры присоединились к проекту, большинство считали, что Pupil и Student — это разные концепции.

Используйте Отраслевую Терминологию

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

Большинство инженеров-программистов, когда видят что-то с именем “factory”, сразу думают о паттерне фабрика.

Использование существующих парадигм приложений, таких как “Clean Architecture” и “Domain Driven Design”, способствует обмену идеями и создает общий язык для инженеров для общения идей между собой.

Худшее возможное именование — это присвоение отраслевой терминологии и придание ей другого значения.

При Именовании Булевых Значений…

Имена булевых значений всегда должны быть ответом на вопрос со значением либо true, либо false.

Например, isUserAuthenticated, ответ либо да (true), либо нет (false)

Используйте слова вроде:

• Has
• Does
• Is
• Can

Избегайте отрицательных имен, например:

Отрицательное имя переменной:

var IsNotDeleted = true; // это сбивает с толку

if(!IsNotDeleted) { // становится еще более сбивающим с толку, когда значение отрицается
  //Do magic
}

Без отрицательного имени переменной:

var IsDeleted = true; // это понятно

if(!IsDeleted) { 
  //Do magic
}

В Заключение

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