pin2t May 25 2021 at 06:10

Именуйте классы, переменные и функции для людей, а не для машин

4 min

6.9K

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

TL,DR

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

Компилятор, машина, без проблем поймет хоть shouldDisplayPagination, хоть p, ей без разницы. В отличии от человека. Проблема с именем shouldDisplayPagination в том, что слишком перегружено ненужными деталями. Средний человек способен оперировать одновременно небольшим количеством объектов в памяти. Примерно три-четыре, до семи. Поэтому, пока он читает слова should, display, pagination, у него из памяти вытесняются другие объекты, возможно детали алгоритма, которые он пытается понять, читая исходный код. В итоге, человек хуже поймет алгоритм, и сделает ошибку при его исправлении или использовании. Слишком описательные названия, как ни странно, ведут к прямо противоположному результату, к ухудшению понимания и большему количеству ошибок.

Любая система именования переменных, хоть венгерская нотация (если кто-то её ещё помнит), хоть современный аббревиатурный подход (P)A/HC/LC, ухудшает читаемость и поддерживаемость кода. Потому что он делает код в виде текста более похожим на машинно генерируемый код, прекрасно воспринимаемый машиной, но плохо воспринимаемый человеком. Некоторые принципы именования переменных, о которых речь пойдет ниже, в целом хорошая идея, но системы с табличками, колонками и строками, однозначно нет. Названия не вписываются в жесткую структуру табличек.

Далее по пунктам.

Префиксы

От использования префиксов в целом лучше воздержаться. Потому что они повторяют очевидную вещь, тип значения, возвращаемого функцией. Нет смысла повторять уже существующую информацию. Единственным исключением является префикс is- который очень широко используется в стандартной библиотеке (речь про Java). has- и should- тоже есть, но уже гораздо меньше, и их использовать не надо.

Во всех приведенных примерах переменные вообще ненужны, потому что само выражение достаточно короткое, вместо

const color = 'blue';
const isBlue = (color === 'blue'); // свойство
const isPresent = true; // состояние

if (isBlue && isPresent) {
  console.log('Blue is present!');
}

лучше

const color = 'blue';
const isPresent = true; // состояние

if (color === 'blue' && isPresent) {
  console.log('Blue is present!');
}

Вместо

const hasProducts = (productsCount > 0);

лучше

productsCount > 0

там где используется переменная hasProducts. Да и productsCount слишком длинное название для переменной, лучше products или count.

Действие

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

Совершенно определенно следует отказаться от префиксов get- и set-. Если функция возвращает какое-то значение, то её название должно описывать, что возвращает функция, глагол get- совершенно избыточен

Соответственно, не

function getFruitsCount() {
  return this.fruits.length;
}

function fruitsCount() {
  return this.fruits.length;
}

Когда программист читает

if (getFruitsCount() > 10)

или

if (fruitsCount() > 10)

понятность этого кусочка кода одна и та же, но в первом случае ему необходимо прочитать просто больше слов. Слово get- не добавляет нисколько дополнительной информации.

Префикс set- описывает действие на слишком низком уровне, тем самым разрушая инкапсуляцию. Например, вместо setName лучше название rename. Приведенный в статье пример опять слишком простой, и не описывает достаточно зачем нужна эта функция вообще, вместо

let fruits = 0;
const setFruits = (nextFruits) => {
  fruits = nextFruits;
};
setFruits(5);
console.log(fruits); // 5

опять гораздо лучше будет

let fruits = 0;
fruits = 5;
console.log(fruits); // 5

Далее, если название начинается с глагола, функция не должна возвращать значение. Таким образом

const fetchPosts = (postCount) => fetch('https://api.dev/posts', {...});

вариант не очень. Если это функция, то должна описывать то что возвращает, соответственно

const posts = (count) => fetch('https://api.dev/posts', {...});

Если это метод класса, то он должен изменять состояние объекта, но не возвращать значение

class ApiPosts {
    var posts
    void fetch(count) { posts = fetch('https://api.dev/posts', {...}); }
}

S-I-D

Да короткие названия это хорошо (S), но пример

const shouldDisplayPagination = (postsCount > 10); // альтернатива

совершенно точно таким не является

const pagination = (postsCount > 10); // альтернатива

или

postsCount > 10

уже гораздо лучше.

Сокращения

В целом сокращения это плохо, но иногда, если переменная используется в трех строчках кода, нет ничего плохого в сокращении

for (URI u: uris) {
    pages.fetch(u);
}

читается гораздо легче и понятнее, чем

for (URI uriToFetch : urisArray) {
    pagesCollection.fetch(uriToFetch);
}

PS: Наименования переменных, функций и классов это сложно. Сложно подобрать понятные, очевидные и подчеркивающие предметную область названия. Но совершенно точно эти названия нельзя уложить в стройную аббревиатурную систему (P)A/HC/LC, XYZ или любую другую. Потому что многообразие предметных областей, программ, обрабатывающих данные, не описывается простой табличкой.

Tags:

Hubs:

Programming