Ниже представлена подборка типичных ошибок, которые допускают программисты при именовании переменных и функций в своём коде. Примеры взяты из проектов учеников Хекслета. В качестве языка для демонстрации я использую 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. А как мы помним, имя должно сразу говорить о своём смысле без необходимости додумывать.
Транслитерация
Самый короткий пункт. Имена в стиле chislo или noda говорят о том, что автор этого кода не умеет и не хочет пользоваться переводчиком.
Расскажите в комментариях о своём опыте. Какие имена переменных вы встречали?
Дополнительные материалы
