Именование ваших переменных!

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

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

Назначение переменной должно быть ясным

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

elapsedTimeInDays , daysSinceOpenning , daysSinceClosing, personAgeInDays

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

Вы можете догадаться, зачем нужен этот код?

Трудно догадаться, что делает этот код, правда? Но почему? Нет сложных выражений. Также допустимы интервалы и отступы. Упомянуты только некоторые переменные и константы. Нет даже навороченных классов или полиморфных методов.

Проблема не в простоте кода, а в его скрытом виде! : P Из-за скрытности мы не знаем ответа на следующий вопрос:

Какие вещи / ценности есть в theList?
Какое значение имеет zeroth index элемента в theList?
Какое значение имеет значение 4 и почему мы здесь используем 4?
Какие значения возвращаются с помощью list1?

Ответов на эти вопросы нет в примере кода, но они могли быть.

Давай, мы работаем в игре с тральщиком. Мы обнаруживаем, что доска представляет собой список ячеек с именем theList. Давайте переименуем это в gameBoard. Каждая ячейка на доске представлена простым массивом. Далее мы обнаруживаем, что нулевой индекс - это местоположение status value, а значение статуса 4 означает flagged.

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

Обратите внимание, что простота кода не изменилась, но теперь она стала более явной! Он по-прежнему имеет точно такое же количество операторов и констант.

Мы можем пойти дальше и написать простой class для ячеек вместо использования array целых чисел. Он может включать функцию выявления намерений (назовите ее isFlagged), чтобы скрыть магические числа.

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

Избегайте дезинформации

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

Например, мы хотим сохранить информацию о счете клиента банка, и эта информация не указана в list, но если мы используем переменную accountList для хранения значения, она не будет давать соответствующего указания. Мы не должны добавлять слово «список» после имени любой переменной, если это на самом деле не List.

Теперь, если мы хотим сохранить много учетных записей в контейнере, и учетные записи могут быть любого (контейнерного) типа (например, list, queryset, array и т. Д.), Тогда лучше использовать accountGroup или bunchOfAccounts в качестве имени переменной.

Две переменные, названия которых отличаются небольшими частями, также могут вас запутать.
Пусть, testVariableNameFromClassA, testVariableNameFromClassB эти два являются допустимыми переменными, но их легко поменять местами по ошибке.
Кроме того, функция автозавершения кода в современных IDE может усложнить задачу!

Одна из распространенных проблем начинающих программистов - это использование одного символа, такого как O или o, в нижнем регистре L (l) в качестве имени. Это может вызвать серьезные проблемы при отладке.

Как видите, этот код достаточно неоднозначен, чтобы вас запутать!

Имя переменной должно иметь значимую уникальность.

Имя переменной должно четко выражать ее цель и значение.

Почувствуйте разницу между удобочитаемостью следующих фрагментов кода:

Допустим, у вас есть три функции:

getActiveCustomer();
getActiveCustomers();
getActiveInfo();

Сможете ли вы угадать назначение каждой функции? Трудно догадаться, какую функцию вызывать с какой целью. Это сила двусмысленности! :П

Имена должны быть произносимыми

Люди умеют говорить. Все, что хорошо произносится, легко уловить.

Допустим, у нас есть функция с именем getDMY(), которая возвращает день-месяц-год расписания. Допустим, вам нужно кому-то описать свой код. Теперь, как будет произноситься getDMY? Не знаете, ДА?
Переименование на getDayMonthYear() может мгновенно решить вашу проблему!

Размер имени переменной и возможность поиска

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

Длина имени переменной должна соответствовать размеру ее области видимости.
Однобуквенное имя следует использовать только как локальную переменную внутри коротких методов / функций.

Традиционно мы используем i, j или k (осторожно: не l или o) для управления циклом, если его область действия очень мала.
Лично я предпочитаю не использовать однобуквенные переменные (кроме цикла с небольшой областью видимости).

Имя должно быть легко доступным для поиска и заменяемым.

Этот код тоже неоднозначен. Если мы хотим заменить 50, 4 или 5, это может быть слишком болезненно. Потому что в коде может быть больше констант с одинаковым значением, и они могут быть ошибочно заменены.

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

Имена классов и имена методов / функций

Имя класса и имя объекта должны быть существительным или существительным (например: Пользователь-Клиент, Учетная запись и т. д.).
Вам следует избегать таких слов, как Data, Information или Info ( Они не дают четкого объяснения класса или объекта (могут быть разные типы данных или информации).
Настоятельно не рекомендуется использовать глагол в качестве имени класса.

Имя метода / функции должно быть глаголом или глагольной фразой (например: удалить, сохранить, опубликовать и т. д.).
Методы установки должны иметь префикс set, а методы получения должны иметь префикс get.

* * * Небольшие заметки, спасающие жизнь

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

Вежливость

Некоторые примеры в этой статье взяты из замечательной книги Роберта К. Мартина Чистый код .

Заключение

Хороший навык описания помогает в хорошем нейминге. На практике он постепенно развивается день ото дня.

Вы также можете прочитать:

Эта история публикуется в Noteworthy, куда ежедневно приходят более 10 000 читателей, чтобы узнать о людях и идеях, формирующих наши любимые продукты.

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