Какие имена переменной правильные
Перейти к содержимому

Какие имена переменной правильные

  • автор:

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

В компьютерном программировании соглашение об именах — набор правил для выбора последовательности символов, которая будет использоваться для идентификаторов, которые обозначают переменные, типы, функции и другие объекты в исходном коде и документации, — «Википедия»

Придумывать названия сложно!

В этой статье мы сосредоточимся на методе именования (P)A/HC/LC для того, чтобы улучшить читаемость кода. Эти рекомендации можно применить к любому языку программирования, в статье для примеров кода используется JavaScript.

Что значит (P)A/HC/LC?

В этой практике используется следующий шаблон для именования функции:

Что обозначает префикс (P)?

Префикс расширяет смысл функции.

Описывает свойство или состояние текущего контекста (обычно — логическое значение).

Указывает, имеет ли текущий контекст определенное значение или состояние (обычно — логическое значение).

Отражает положительный условный оператор (обычно — логическое значение), связанный с определенным действием.

Действие — это сердце функции

Действие — это глагольная часть имени функции. Это самая важная часть в описании того, что делает функция.

Получает доступ к данным немедленно (сокращение от getter для внутренних данных).

Безусловно присваивает переменной со значением A значение B.

Возвращает переменную к её начальному значению или состоянию.

Выполняет запрос данных, для которого требуется время (например, асинхронный запрос).

Удаляет что-то откуда-то.

Например, если у вас есть коллекция выбранных фильтров на странице поиска, удаление одного из них из коллекции — это removeFilter , а не deleteFilter (именно так вы и скажете на английском языке):

Полностью стирает что-то. После операции сущность перестаёт существовать.

Представьте, что вы редактор контента, и есть пост, от которого вы хотите избавиться. Как только вы нажали на кнопку delete-post, CMS выполнила действие deletePost , а не removePost .

Создает новые данные из существующих. Обычно это применимо к строкам, объектам или функциям.

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

Контекст

Контекст — это область, с которой работает функция.

Функция — это часто действие с чем-то. Важно указать, какова её рабочая область или, по крайней мере, ожидаемый тип данных.

В итоге

Пять принципов именования переменных

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

1. Следуйте S-I-D

Имя должно быть коротким (Short), интуитивно понятным (Intuitive) и описательным (Descriptive).

2. Избегайте сокращений

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

3. Избегайте дублирования контекста

Всегда удаляйте контекст из имени, если это не снижает его читабельность.

4. Отражайте в имени ожидаемый результат

5. Учитывайте единственное/множественное число

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

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

Как называть переменные и функции, чтобы вас уважали бывалые программисты

Если вы опытный разработчик, покажите эту статью начинающим.

Зачем как-то по-особому называть переменные и функции

Вам по-любому придётся как-то назвать переменные и функции. С точки зрения языков программирования, переменные могут быть почти любыми: хоть a, b и c, хоть SuperImportantVariable3000. То же с функциями: они могут быть суперкороткими типа yo(), а могут быть невероятно замороченными вроде getNewPageNumberAndNavigateToThatPage(). Как скажете — так и будет. Тем более что современные текстовые редакторы делают автоподстановку всех названий, так что вам даже не придётся их запоминать.

Но есть три момента:

  • Через две недели вы уже забудете, как был устроен ваш код. Если вы написали программу сегодня и вернулись к ней через 14–21 день, вы уже не сможете на ходу вспомнить, за что отвечают разные куски кода. И если по переменной или функции будет понятно, что она делает, то вы себе очень упростите задачу.
  • С вашим кодом обязательно будет работать кто-то другой. Вы сделали классную программу, она функционирует, и вы приглашаете кого-нибудь тоже поработать над ней. Он откроет ваш код и должен будет в нём разобраться. Если переменные и функции названы хорошо, ему будет легко всё понять и он быстро вам поможет.
  • Это влияет на приём на работу. Если решите связать свою жизнь с программированием, по названиям ваших переменных и функций будут судить о ваших качествах как специалиста. Программа может, конечно, работать и без красивого названия переменных, а вот вас в компанию могут и не позвать.

Как называть переменные

Когда начинаешь писать код, у тебя простые программы, к которым нужны простые переменные: screen, score, text и так далее. Потом проекты становятся сложнее, и переменные нужны всё более сложные: totalScore, totalScoreBefore, totalScoreAfter, totalScoreMaxProgressiveLimit и тому подобные. Тут надо остановиться и подумать вот о чём.

Чем длиннее название переменной, тем тяжелее её набрать без ошибок. Спасает автоподстановка, но если её нет — почти наверняка ваш код не полетит из-за опечатки.

Если вы пишете на JavaScript, то будет ещё хуже: так как он генерирует переменные на ходу, ошибка в переменной totalScoreMaxProgresLimit у него не вызовет подозрений. Он создаст новый элемент с этим названием, и у вас будут две переменные — одна правильная, другая неправильная. Программа запустится, но работать будет непредсказуемо.

Поэтому стремитесь выбирать короткие названия переменных, которые при этом понятны без глубокого вникания. Например, totalScore — итоговый счёт в игре, maxWidth — максимальная ширина. Если есть необходимость хранить много переменных на разных полочках, в группах или еще какими-то пачками, изучите понятия объектов и классов в JavaScript — это то, что вам нужно.

Как называть функции

Функция — это подпрограмма внутри вашей программы, которую вы часто используете. Например, можно написать функцию getNumber(), которая будет выдавать случайное число в нужном вам диапазоне. Или сказать setTimer() — и где-то внутри программы установится таймер, который выполнит то, что необходимо, по завершении отсчёта времени.

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

У функций тоже могут быть какие угодно названия. Но обычно они будут примерно такими:

  • shuffle() — скорее всего, перемешает элементы массива;
  • saveScore() — сохранит куда-то счёт игры;
  • kill() — убьёт что-то;
    spawn() — создаст что-то;
  • loadDatabase() — загрузит какую-то базу данных в память;
  • makeBackup() — сделает резервную копию каких-то данных и, скорее всего, сохранит её куда следует;
  • getSpeed() — выяснить, с какой скоростью что-то движется. Функция вернёт скорость;
  • getUserName() — что-то произойдёт, и функция вернёт имя пользователя;
  • getSessionId() — вернёт номер сессии;
  • setTimeout() — задать задержку, после которой произойдёт какое-то действие;
  • setSpeed() — задать чему-то скорость.

Вы заметите, что из названия функции можно понять, что она сделает и сообщит ли какой-то результат. Например, getScore() вернёт счёт игры, setScore() задаст счёт игры и ничего не вернёт, а clearScore() обнулит счёт игры и тоже ничего не вернёт.

А что с заглавными буквами?

В программировании есть два подхода к оформлению функций и переменных: camelCase и snake_case.

В camelCase переменные из нескольких слов соединяются без пробела, все новые слова пишутся с заглавной: getMoney, renderToFrame, removeFromBase и т. д. Этот подход рекомендуется в JavaScript. Обратите внимание: названия переменных и функций в JavaScript чувствительны к заглавным, то есть переменные getmoney и getMoney — это разные переменные.

Snake_case — это когда слова склеиваются нижним подчеркиванием. Это чаще используют в классах CSS. Примеры: header_marginal, form_success.

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

Как не надо называть ни переменные, ни функции

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

Но, например, unicornCount — нормальная переменная с количеством единорогов. А initWorld() — функция, которая создаёт мир компьютерной игры.

Не называйте функции и переменные словами function или variable. MyVar и superFunction() — плохие варианты, потому что вы сами же через две недели забудете, что эти штуки делают.

Лучше не называть функции и переменные по-русски типа solnce или KYCb() — забудете потом, как они правильно пишутся. А когда ваша программа станет международно признанной, разработчики поблагодарят вас. При этом: если ваша функция делает «кусь», чтобы это ни значило, ее можно назвать bite() или getPiece().

Не делайте названия слишком секретными: переменные p, m, t, z или функция hm() — это слишком коротко. Исключение — когда вы пишете циклы: там используются переменные типа i, n, p — с их помощью считают, сколько раз цикл уже отработал. Но эти переменные создались, исполнили свою роль и уничтожились сразу после закрытия цикла, больше к ним не обращаются.

Выбираем имена для переменных с учетом грамматики

Перевод статьи «A Grammar-Based Naming Convention».

Как выбирать имена для переменных

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

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

Чтобы сэкономить силы и время, я во всех своих проектах выбираю имена для переменных в соответствии с несколькими простыми правилами. Сегодня я хочу поделиться ими с сообществом, чтобы и другие люди могли тратить меньше времени на обдумывание имен переменных.

Примечание: примеры кода, приведенные в этой статье, написаны на JavaScript, но подходят для любого языка, ведь речь идет только об именах.

Основные правила

Все переменные, функции, параметры и идентификаторы пишутся в camelCase. Константы пишутся в SCREAMING_CASE. Это важное разграничение, позволяющее с первого взгляда определять, какие переменные неизменяемы и по своей природе используются только для чтения.

В языках программирования, где неизменяемые переменные настоятельно поощряются (или даже являются обязательными), мы должны разграничивать неизменяемые переменные и истинные константы.

Любое статичное значение, не зависящее от пользовательского input или других динамичных значений, можно классифицировать как истинную константу. Например, значение PI это определенно истинная константа, поэтому ее имя должно писаться в SCREAMING_CASE. А camelCase используется для обозначения изменяемых и неизменяемых переменных, хранящих временных значения, псевдонимы, результаты вычислений и выходные данные, зависящие от выполнения программы.

[javascript]// Immutable Variables
const userInput = document.getElementsByTagName(‘input’)[0].value;
const hasDevto = /dev\.to/g.test(userInput);

// True Constants
const WEBSITE_NAME = ‘dev.to’;
const TAU = 2 * Math.PI;
[/javascript]

Но следует учитывать влияние контекста. Критерий разграничения неизменяемых переменных и истинных констант может меняться в зависимости от ситуации. Например, можно использовать SCREAMING_CASE для userInput, если он будет использоваться как статичное значение на протяжении всей работы программы (даже если он может отличаться при запуске программы на разных устройствах). В конечном итоге, лишь от программиста зависит, как проводить линию размежевания между неизменяемыми переменными и истинными константами.

Семантические типы данных

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

Числа, строки и объекты

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

[javascript]const usernameInputField = document.getElementById(‘username-field’);
const username = nameInputField.value;
const hypotenuse = Math.sqrt(a**2 + b**2);
const profileData = <
name: ‘Presto’,
type: ‘Dog’
>;[/javascript]

Булевы значения

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

[javascript]// Yes-or-no questions
const isDog = true;
const hasJavaScriptEnabled = false;
const canSupportSafari = false;
const isAdmin = false;
const hasPremium = true;

// Functions or methods that return booleans
// are also named in a similar fashion
function isOdd(num) < return Boolean(num % 2); >[/javascript]

Массивы и коллекции

Для имен массивов и прочих структур данных, напоминающих коллекции (например, Map и Set) используются наиболее подходящие имена существительные во множественном числе, записанные в camelCase.

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

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

[javascript]// We use plural or collective nouns for arrays.
const dogs = [ ‘Presto’, ‘Lucky’, ‘Sparkles’ ];

// We can use the singular form of the
// variable name of the array
// in callback functions.
dogs.forEach(dog => console.log(dog));

// We can also use it in `for…of` loops.
for (const dog of dogs)
console.log(dog);

// Here, we can use collective nouns
// for better readability.
const herdOfCows = [ ‘Bessie’, ‘Bertha’, ‘Boris’ ];
herdOfCows.forEach(cow => console.log(cow));
for (const cow of herdOfCows)
console.log(cow);[/javascript]

Функции

Имена функций выбираются в привязке к их действию. Поэтому они часто состоят из двух частей: переходного глагола и объекта, на который направлено действие этого глагола. Другими словами, имена функций обычно соответствуют формуле глагол + существительное. Это говорит нам о том, что имя является командой, т. е., функцией, которую мы можем вызывать при необходимости.

[javascript]function getSum(a, b) < return a + b; >
function findBanana(str) < return str.indexOf(‘banana’); >
function getAverage(numbers) <
const total = numbers.reduce((prev, curr) => prev + curr);
return total / numbers.length;
>[/javascript]

PowerShell, эквивалент Bash для Windows, это прекрасный пример языка, принудительно применяющего соглашение об именах для функций (или командлеты – как они называются в этом языке).

Приведенный ниже скрипт вычисляет общий объем памяти, выделенной для всех запущенных в настоящее время процессов Chrome. Синтаксис этого скрипта не самый дружественный, но в нем отлично видно обязательное использование формулы глагол + существительное для командлетов в PowerShell. Здесь задействованы только командлеты Get-Process, Where-Object и Measure-Object, но будьте уверены, что другие командлеты в PowerShell тоже соответствуют указанной формуле. Вот на этом сайте можно посмотреть их все.

[javascript]# Get all processes currently running
$processes = Get-Process;

# Filter to retrive all Chrome processes
$chromeProcesses = $processes | Where-Object

# Sum up all of the memory collectively
# allocated for the Chrome processes
$memoryUsage = $chromeProcesses | Measure-Object WorkingSet64 -Sum;

# Log the result to the console
" <0:F2>MB used by Chrome processes." -f ($memoryUsage.Sum / 1mb);[/javascript]

Классы

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

[javascript]class User < >
class Admin extends User < >
class Moderator extends Admin < >
class Player extends User < >[/javascript]

Поля и методы классов

Поля классов именуются в соответствии с правилами относительно изменяемости и типов данных, о которых мы говорили ранее.

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

[javascript]// Class
class Player <
constructor(name) <
// String
this.username = name;

// Number
this.level = 100;

// Boolean
this.isAdmin = false;

// Class Method (with noun)
initiateBattle()

// Class Method (without noun)
attack() < >
>[/javascript]

Заключение

[javascript]const TRUE_CONSTANT = Math.PI;
const stringName = »;
const numberName = 0;
const isBooleanName = true;
const objName = < >;
const arrayNames = [ ].map(name => name);
function getFunctionName() < >
class ClassName < >[/javascript]

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

При желании мы могли бы просто добавить ко всем переменным приставки с сокращенной пометкой о типе данных. Но таким образом имена стали бы излишне многословными. Пример вы можете видеть ниже.

[javascript]// This is… eww. &#x274c;
const NUM_TAU = 2 * Math.PI;
const str_Username = ‘Some Dood’;
const num_Hypotenuse = Math.sqrt(num_A**2 + num_B**2);
const boo_AdminStatus = false;
const obj_ProfileData = < >;
const arr_Articles = [ ];
function fun_GetUser() < >
class Cls_Class < >[/javascript]

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

Язык программирования называется языком не без причины…

Как называть переменные?

Если вы начали программировать, в какой-то момент вам придется подумать, как называть свои переменные и функции. С точки зрения языка программирования названия у них могут быть любыми: от i до MySuperVariable100500.

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

Почему названия переменных важны

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

Правила именования

  • Имя переменной или функции должно отражать намерение — прочитав его, должно стать понятно, зачем нужна именно эта сущность. Хотя выбор имен отнимает время, при рефакторинга кода с плохим именованием его тратится намного больше.
  • Имя любой переменной, функции или класса должно отвечать на три вопроса:
  • Почему оно существует? 2.Что делает?
  • Для чего используется?

Лучше выбирать короткие имена, так как чем длиннее названия переменных, тем тяжелее их набрать без ошибок(хоть тут помогает автокомплит).

Часто функции называют каким-то действием. Например, getUserName() задает имя пользователя, а setSpeed() — скорость.

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

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *