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

Введение

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

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

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

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

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

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

Переменные

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

• Предмет 

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

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

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

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

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

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

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

Примеры: 

Функции

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

• Действие 

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

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

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

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

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

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

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

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

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

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

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

Примеры:

Части речи

Предмет

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

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

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

Примеры:

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

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

Примеры:

Действие

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

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

Примеры:

• Go! (Иди!)

• Stop! (Остановись!)

• Read! (Читай!)

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

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

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

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

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

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

Примеры:

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

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

Примеры:

Исключения

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

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

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

• Флаги

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

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

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

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

• Хуки

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

Заключение

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