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

Введение

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

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

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

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

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

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

Переменные

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

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

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

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

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

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

Примеры:

Функции

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

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

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

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

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

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

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

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

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

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

Примеры:

Части речи

Предмет

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

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

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

Примеры:

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

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

Примеры:

Действие

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

Поместить глагол в форму повелительного наклонения в английском языке очень легко. Нужно просто взять инфинитив (его базовую форм) без частицы 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

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

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

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

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

Примеры:

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

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

Примеры:

Исключения

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

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

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

• Флаги

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

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

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

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

• Хуки

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

Заключение

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

© Habrahabr.ru