Основные принципы хорошего нейминга

a07a60b6ebc0e099d9230761e10c450d

Введение

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

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

Переменные и функции

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

Функции описывают поведение. Многие более сложные конструкции, такие как хуки, генераторы, методы объектов или классов, в основе своей являются функциями.

Разберем по частям

Переменные

Разделим названия переменных на три части:  

Предмет — основная сущность, к которой относится переменная.

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

Атрибут Предмета — это составляющая или часть предмета. 

Последовательность этих частей всегда следующая:

Признак Предмета > Предмет > Атрибут Предмета 

Примеры:

Имя переменной

Признак

Предмет

Атрибут

user

user

Пользователь

activeUser

active

user

Активный пользователь

userID

user

ID

ID пользователя

activeUserID

active

user

ID

ID активного пользователя

Функции

Разделим названия функций на три части:

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

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

Контекст Действия — это опциональная часть названия функции, которая уточняет дополнительные условия или характеристики выполнения действия.

Последовательность этих частей всегда следующая:  

Действие > Предмет (полный) > Контекст Действия

Почему последовательность именно такая?

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

Такой порядок облегчает восприятие, так как код читается в логической последовательности: Что делать? > С чем? > В каком контексте?  

Становится проще искать нужную функцию или переменную через автозаполнение. Например, введя get, вы увидите список функций, которые что-то получают. Затем, продолжив ввод getTasks вы увидите список функций, которые получают tasks. И из них сможете выбрать ту конкретную, которая больше всего подходит вам по контексту, например, getTasksByIds.

Примеры:

Имя функции

Действие

Предмет (полный)

Контекст действия

getUser

get

User

Получи пользователя

getActiveUser

get

ActiveUser

Получи активного пользователя

getUserName

get

UserName

Получи имя пользователя

getActiveUserName

get

ActiveUserName

Получи имя активного пользователя

getUserByID

get

User

ByID

Получи пользователя по ID

getActiveUserByID

get

ActiveUser

ByID

Получи активного пользователя по ID

getUserNameByID

get

UserName

ByID

Получи имя пользователя по ID

getActiveUserNameByID

get

ActiveUserName

ByID

Получи имя активного пользователя по ID

Части речи

Предмет

Предмет — это существительное, во множественном или единственном числе.

Признак Предмета

Признак Предмета может быть выражен прилагательным или причастием.

Примеры:

Имя переменной

Признак Предмета

activeUser

active

Активный пользователь

pendingOrder

pending

Находящийся в обработке заказ

premiumProduct

premium

Премиальный товар

Атрибут Предмета

Атрибут Предмета может быть выражен через существительное или комбинацию нескольких существительных.

Примеры:

Имя переменной

Атрибут Предмета

orderDeliveryDate

Date

Дата доставки заказа

userProfilePicture

Picture

Изображения профиля пользователя

paymentTransactionID

ID

ID транзакции определенного платежа

Действие

Действие — это глагол в повелительном наклонении.

Поместить глагол в форму повелительного наклонения в английском языке очень легко. Нужно просто взять инфинитив (его базовую форм) без частицы to. 

Примеры:

Запомнить, что глагол должен быть в повелительном наклонении можно проведя вот такую аналогию.

class Spellbook {
    // Описание заклинания: откройЗамокПоАйди!
    openLockByID(id) {
        console.log(`Произношу заклинание для замка с ID: ${id}`);
        console.log(`Замок с ID: ${id} распахивается с щелчком!`);
    }

    // Описание заклинания: киньФаерболлПоXYZ!
    throwFireballByXYZ(x, y, z) {
        console.log(`Собираю энергию для огненного шара...`);
        console.log(`Огненный шар летит к координатам (${x}, ${y}, ${z}), сжигая всё на своём пути!`);
    }
}

const spellbook = new Spellbook();
// Вызовы заклинаний
spellbook.openLockByID(7); // откройЗамокПоАйди 7
spellbook.throwFireballByXYZ(10, 20, 30); // киньФаерболлПоXYZ  10 20 30

В то время как на самом деле вы пишете что-то вроде такого.

class BoardManager {
    // Описание функции: откройДоступКДокументуПоАйди!
    unlockDocumentAccessByID(id) {
        console.log(`Ищу документ с ID: ${id}`);
        console.log(`Документ с ID: ${id} в публичном доступе.`);
    }

    // Описание функции: отправьУведомлениеПоГеолокации!
    sendNotificationByLocation(latitude, longitude) {
        console.log(`Ищу пользователей в геолокации (${latitude}, ${longitude})...`);
        console.log(`Отправляю уведомление всем пользователям на координатах (${latitude}, ${longitude})!`);
    }
}

const boardManager = new BoardManager();
// Вызовы функций
boardManager.unlockDocumentAccessByID(7); // откройДоступКДокументуПоАйди 7
boardManager.sendNotificationByLocation(55.7558, 37.6173); // отправьУведомлениеПоГеолокации 55.7558, 37.6173

Контекст Действия

Контекст Действия может быть выражен двумя основными способами: сочетанием существительного с предлогом или условным выражением.

Существительное с предлогом

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

Примеры:

Имя функции

Контекст Действия

fetchDataByDateRange

ByDateRange

Данные запрашиваются в пределах указанного диапазона дат.

sendNotificationForUser

ForUser

Уведомление отправляется для определенного пользователя. 

calculateTaxOnAmount

OnAmount

Налог рассчитывается на определенную сумму.

Условное выражение

Условное выражение в контексте действия описывает условия или проверки, при которых действие будет выполнено. 

Примеры:

Имя функции

Контекст Действия

restartServiceIfInactive

IfInactive

Сервис перезапускается только если он неактивен.

clearCacheWhenExpired

WhenExpired

Кэш очищается, когда он устарел.

lockAccountOnFailure

OnFailure

Аккаунт блокируется при неудачной попытке входа.

Исключения

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

  • Односимвольные переменные

  • Промежуточные вычисления

  • Флаги

  • Замыкания и функции обратного вызова

  • Абстрактные концепции

  • Интерфейсы или API-интеграции

  • Стандартные методы и свойства

  • Хуки

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

Заключение

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

© Habrahabr.ru