Хабрахабр

[Перевод] Как придумывать содержательные имена для вашего кода

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

Имена повсюду: они нужны для файлов, классов, методов и тех самых переменных. Будучи разработчиком, вы наверняка тратите много времени на создание переменных и придумывание их имен.

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

Используйте имена, раскрывающие ваши намерения

Имя должно указывать на цель кода. Проще сказать, чем сделать, да? Как часто вам встречаются переменные с названиями, которые ничего не говорят о замысле программиста?

Правило такое: если имя требует комментариев, оно не передает намерение.

В данном отрывке кода есть переменная, по имени которой не ясно ее назначение:

<?php
private $s; // Time in seconds

Переменная $s нам ни о чем не говорит и не ассоциируется с периодом времени. Лучше выбрать имя, которое будет указывать, что и в каких единицах измеряется.

Одно из приведенных ниже имен было бы более подходящим.

<?php
private $days_since_creation;
private $elapsed_time_in_seconds;
private $seconds_since_last_modified;

Имена, выражающие намерение, делают код более простым для понимания, и, следовательно, поддерживать его тоже становится проще.

Вы потратите время на выбор подходящего имени, но зато сэкономите его в будущем.

Рассмотрим такой пример:

<?php
function getList() } return $list1;
}
function getOddNumbers() { $odd_numbers = []; foreach ($this->numbers as $number) { if (isOdd($number)) { $odd_numbers[] = $number; } } return $odd_numbers;
}

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

Увидели, что она делает то же самое, что и getList? А теперь посмотрите на функцию getOddNumbers.

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

Небольшое изменение в имени — и уже намного легче понять, что происходит.

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

Старайтесь избегать ложных ассоциаций, искажающих назначение кода.

Например, не называйте группу продуктов productList, если только это действительно не объект типа List. Не используйте слова, которые можно понять не так, как вы задумывали. Лучше использовать просто products. Такое имя может привести к ложным выводам.

Пожалуй, худшие имена для переменных начинаются с прописной буквы O и строчной L, так как эти символы очень похожи на 0 и 1.

Сколько времени пройдет, пока вы заметите небольшую разницу между SomeMethodForEfficientHandlingOfFiles в одном файле и SomeMethodForEfficientStorageOfFiles в другом? Также с осторожностью используйте имена, которые лишь немного отличаются друг от друга. Согласитесь, на первый взгляд они идентичны.

Подчеркивайте осмысленные различия

Использование нумерации не лучший способ присвоения имен. Такие имена неинформативны, так как совсем не раскрывают намерения автора.

Посмотрим на следующий пример:

<?php
public function duplicateArray($arr1, &$arr2) { foreach ($arr1 as $key => $value) { $arr2[$key] = $value; }
}

Данный отрывок кода будет читаться лучше, если мы переименуем $arr1 и $arr2 в $source и $destination.

Используйте имена, которые можно произнести

Если у вас не получается произнести имя функции, то вряд ли вы сможете говорить о ней и не звучать по-идиотски. Это вообще-то важно, потому что обсуждение кода является частью программирования. Тем не менее каждый из нас наверняка встречал переменные с непроизносимыми названиями.

И вот вы разговариваете с коллегой:
— Ну что там с экс эс кью?
— С чем-чем? Представим, что у вас есть переменная с именем $xsq и вы часто обсуждаете ее в компании. С access queue?

Кто-то из разработчиков произнесет имя переменной как слово, а кто-то — как аббревиатуру.

Используйте имена, удобные для поиска

Проблема с именами, состоящими из одной буквы, в том, что их сложно найти в коде.

Их лучше заменить переменными. То же самое и с числовыми константами. Однако будет намного проще, если заменить число на что-то вроде MAX_BLOCKS_DISPLAYED. К примеру, обычная цифра 8 может доставить кучу проблем, если надо будет что-то найти в коде.

Единственная ситуация, в которой стоит использовать имена из одной буквы, — это придумывание названий для локальных переменных внутри коротких методов.

Префиксы членов классов

Не используйте префиксы m_.

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

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

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

Заключение

Вот так и создаются более понятные имена для кода.

Комментируйте, оставляйте свои вопросы и пишите, если хотите, чтобы я осветил другие темы связанные с программированием.

На эту статью меня вдохновила книга Роберта Мартина «Чистый код», которую я очень рекомендую прочесть.

Теги
Показать больше

Похожие статьи

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

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

Кнопка «Наверх»
Закрыть