Основные возможности платформы Hexlet не доступны в вашем браузере.
Пожалуйста, обновитесь. Выбрать браузер.
Разработка

Ошибки именования в программировании I

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

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

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

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

Файл?

Моё "любимое" имя для переменной — 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. А, как мы помним, имя должно сразу говорить о своём смысле, без необходимости додумывать.

Транслитерация

Самый короткий пункт. Имена в стиле chislo или noda говорят о том, что автор этого кода не умеет и не хочет пользоваться переводчиком.

Расскажите в комментариях о своём опыте. Какие имена переменных вы встречали?

Поделиться Вконтакте
Отправить в Телеграм