Совершенный код: ошибки именования в программировании I

~5 минут 299

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

Файл?
Венгерская нотация
Общие названия
Функция — существительное
Сокращения
Парные не парные
Транслитерация

Материалы, на которых базируются принципы именования:

Правильное именование переменных
Ментальное программирование
Ментальное программирование II
Ментальное программирование III

Подписывайтесь на канал Кирилла Мокевнина в Telegram — чтобы узнать больше о программировании и профессиональном пути разработчика

Коротко о смыслах.

Идеально, если одного имени достаточно для понимания того, что находится внутри переменной или что делает функция, а не как она это делает. Если для понимания нужно изучать код вокруг этого имени, то, скорее всего, имя плохое. Основная мысль: Не заставляйте меня (человека, читающего ваш код) думать!

Файл?

Моё «любимое» имя для переменной — file. Особенно прекрасно, когда не видно момента присваивания — например, при передаче этого «файла» в функцию:

const f = (file) => {
  // что-то делаем с «файлом»
};

Что такое файл? Если задать этот вопрос разным людям, то получим разные ответы. Типичный список такой:

Содержимое файла
Имя файла
Путь до файла
Файловый дескриптор

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

Имя file — плохое, оно заставляет проводить в голове трансляцию из имени в его реальную суть: «говорим файл, подразумеваем путь» или «говорим файл, подразумеваем содержимое». Правильные имена: filepath, filename, content.

Венгерская нотация

Венгерская нотация — соглашение об именовании идентификаторов (переменных и функций), которое сводится к кодированию типов данных прямо в название: например, userArray. Подобное именование — это борьба со следствием, а не устранение причины — плохих имён. Рассмотрим некоторые типичные примеры.

Массивы. Если что-то массив, то, значит, у нас есть коллекция каких-то элементов, а у элементов есть имена. Идеальное имя для такого массива — это имя элемента во множественном числе: users, cars, numbers или, на крайний случай, items. Все они явно говорят о том, что мы работаем с коллекцией.
Строки. Здесь всё просто: если мы работаем с произвольной строкой, то её можно назвать text или sentence. В более конкретных случаях это может быть char или word.
Числа. Тут ещё проще: number — он и в Африке number. Но, конечно, лучше давать имя, соответствующее предназначению числа: например, denom (делитель).

Общие названия

В проектах часто можно встретить названия в стиле before или after (встречается вариация new и old). Хочется сразу спросить «Что до?» и «Что после?». Абсолютно непонятно, о чём идёт речь, не зная кода. Конкретно в тех ситуациях, о которых я говорю, имелось ввиду значение до изменений и значение после изменений. Собственно, весь секрет — именовать переменные так, чтобы они отражали эту суть: valueBefore и valueAfter.

Такая же история с функциями. Как вы думаете, что происходит в коде ниже?

process(data);

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

getName(user);

Функция — существительное

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

diff(value) => genDiff(value)
parser(data) => parse(data)
value(user) => getValue(user)

В программировании используется не такой большой набор слов, которые означают различные действия и используются при этом очень часто. К таким словам относятся модальные глаголы и слова типа render, build, generate, show, enable, set, get, edit и другие.

Сюда же можно отнести путаницу с порядком слов. Иногда встречаются подобные варианты: diffBuild, но правильно писать наоборот: buildDiff. Сначала «что делаем?» (какое действие), затем «над чем?» (предмет, на который направлено действие).

Сокращения

Сокращениями в программировании пользуются часто — это нормально. Слова бывают длинные и неудобные, а некоторые сокращения вообще — почти стандарт. Например, назвать number как num — это вполне типичная история. Но иногда встречаются крайне интересные варианты. Я видел такое:

empt (сокращение от empty)
hid (сокращение от hide)

Такое сокращение не просто не делает лучше — оно делает только хуже, так как полное слово внезапно становится неочевидным, да и прочитать такое имя бывает проблематично. Зачем сокращать на одну букву, мне не понятно, но делать так точно не стоит.

А вот длинные имена обычно оказываются хорошим выбором. Не надо их бояться. Например, в Rails есть функции со следующими названиями: distance_of_time_in_words или option_groups_from_collection_for_select.

Парные не парные

В программировании часто встречаются ситуации, для которых идеально подходят антонимы — слова, имеющие противоположный смысл. Например: начало-конец, новый-старый, до-после. И в таких ситуациях нужно уметь правильно подбирать эти слова. Например, какой антоним к слову begin? Правильный ответ: end, а не finish (антоним для start), как думают многие.

Я часто наблюдаю ситуацию, когда в коде только одно слово делают правильным, а второе остаётся нейтральным. Типичный пример: у нас есть старое значение и новое значение. Программист создаёт пару value и newValue. Но это неправильно. Проблема в том, что из этой пары не очевидна связь. Более того, нужно ещё умудриться догадаться, что под value подразумевается oldValue. А как мы помним, имя должно сразу говорить о своём смысле без необходимости додумывать.