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

Преимущества придания именам значимости

Скольких из нас останавливали и удивляли поиски уникального имени для определенной переменной или функции? Известный инженер однажды сказал:

В компьютерных науках есть только две сложные вещи: инвалидация кеша и присвоение имен вещам.

Но почему так важно правильно называть вещи?

Скорее всего, вам знакома эта борьба, когда у вас возникали такие мысли, как «Что вообще означает это имя?», «Какая разница между этим и этим?» или «Что это действительно так?». Немногие из нас знают ценность намеренных имен. Вес этого переносится в будущее. Это может негативно сказаться на вас и вашей команде. Если нет, обратный эффект приведет к улучшению в следующих областях:

  • Последовательность

Знакомство с вашим кодом создает уверенность. Руководство по именованию поощряет это ожидание. Это особенно эффективно в командной среде. Стандарт — это то, что мы хотим использовать, даже в качестве общего руководства. В противном случае мы бы выбирали друг у друга возможности именования и обсуждали их во время проверки кода или на полпути к разработке.

  • Читабельность

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

Мне дали задание немного переработать существующую кодовую базу, когда я обнаружил, что застрял и смотрю на имя. Я не понимал там, пока не посмотрел глубже в реализацию кода. Почему это не могло быть самоочевидным с самого начала?

  • Производительность

Никакие предварительные рекомендации или мысли, заложенные в название, не удержат вас от завершения проекта или задачи.

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

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

Стартовый комплект для руководств по именованию (и лучших практик)

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

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

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

Вот мои выводы из «Чистого кода» и других статей, в которых есть несколько замечательных моментов, которым можно следовать.

Используйте имена, раскрывающие намерения

Думайте о больших вопросах для переменной, функции или класса. Ответьте на следующие вопросы: «почему он существует», «что он делает» и «как он используется».

Измените имена снова, когда вы нашли его настоящую цель

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

Избегайте дезинформации и неинформации

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

  • Аббревиатура может быть дезинформативной.

Как правило, аббревиатура не рекомендуется.
e.g. c может означать «Углерод», «Цельсий» или «Век».

Имена, которые переплетаются с существующими концепциями программирования, сбивают с толку.

например str может означать «сила» или, в терминах программирования, «строка». Это будет варьироваться в зависимости от масштаба проекта, но когда вы делаете ролевую игру, у вас может возникнуть этот конфликт.

Однако я бы сделал исключение для зацикленного списка.

например cards - это массив, и я ожидаю только элемент.

cards.map((c) => c);

c можно было бы переписать как card, но это уже подразумевается.

  • нулевые 0, строчные o, прописные O и строчные l — действительно ужасные имена переменных.

Трудно определить разницу между цифрой ноль, буквой «о», прописной и строчной буквами. То же самое со строчной буквой «l» и цифрой 1. Тем более в сочетании!

e.g.

let a = l;  
if ( O == l )  {
  a = O1;
} else {
  l = 01;
}
  • Именование серий номеров неинформативно.

С тем же успехом они могли быть написаны иероглифами.

e.g.

Array.prototype.swap = function (x1, x2) {
  var b = this[x1];
  this[x1] = this[x2];
  this[x2] = b;
  return this;
}

x1 могло быть source, а x2 могло быть target.

Сделайте значимое различие

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

Делайте дополнительные различия, когда сталкиваетесь со следующим:

  • Окончание множественного числа на «с»

например Множественное число от apple отличается от apples только одной буквой. Неопытным глазом программист может упустить эту второстепенную деталь. Их можно решить, превратив их в собирательные существительные. Подумайте о чем-то вроде basketOfApples или bunchOfApples.

  • Шумовые слова — одинаковое значение, разное написание

Даже не используйте один и тот же термин для двух разных целей.

например В чем разница между totalOfCash и amountOfIncome? Они оба означают одно и то же. Выясните специфику и дифференцируйте.

  • Неразборчивые шумовые слова

например Добавление слов, подобных этим статьям, таких как a, an или the, не означает ничего другого, когда вы просто пишете его название. В их использовании нет ничего плохого. Это просто бесполезно в случае thePerson или aPerson. Сделайте так, чтобы имена отличались более чем на одну или две буквы.

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

function sendEmail(input) {
 const a_txt;
 setMessage(a_txt + input)
}
_________________________________________________ 
function sendEmail(input) {
 const text;
 setMessage(text + input)
}

Более урезанная версия шумовых слов - это когда нет других слов для дальнейшего описания того, что они из себя представляют. Например, total и amount по-прежнему похожи и имеют одно и то же значение, за исключением того, что сами по себе они мало что говорят. "Всего" чего? «Количество» чего?

Используйте произносимые имена

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

Используйте доступные для поиска имена

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

Вот как мы можем сделать имена более доступными для поиска:

  • Используйте более длинные имена вместо более коротких имен

Однобуквенные имена приводят к максимальной двусмысленности. Более длинные имена действуют как лучший идентификатор и дают достаточный контекст.

Есть исключение: однобуквенные имена допустимы в локальных переменных внутри коротких методов. См. пример в разделе Избегайте дезинформации и неинформации в пункте «Аббревиатура может быть дезинформативной», где отображается массив и какие элементы уже подразумеваются.

  • Используйте соглашение об именах констант вместо необработанных значений

например MAX_PASSENGER_ON_BOARD говорит вам больше, чем число 9.

Имена классов

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

  • Имена существительных или именных словосочетаний

Используя существительное, вы понимаете ключевое слово new, которое его инициализирует.

e.g.

const apple = new Fruit("sweet", "crunchy");

Это имеет меньше смысла с присоединенным к нему глаголом или как глагол. например new createFruit(), new Swim().

Подумайте о конкретных словах, о чем-то, что имеет одно ясное значение.

  • Открыт для разных состояний

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

Сделайте имя менее конкретным.

например new FelineDomesticAnimal слишком закрыто от того, что может или не может быть (там написано, что разрешены только кошки). Что-то вроде new Animal позволяет больше разнообразия.

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

например Класс с методами start и end может иметь имя вроде Race, а не FinalRace. «Окончательный» предполагает, что он на стороне метода end.

Сделайте его инклюзивным.

Имена методов

Имена методов должны быть глаголом или названием глагольной фразы.

e.g. saveDocument, playMusic or delete.

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

e.g.

const grade = student.grade();
teacher.setGrade(80);

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

Используйте доменные имена решений

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

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

Добавьте значимый контекст

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

Заключительные замечания

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

Рекомендации