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

Перед вами перевод статьи из блога 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() {
    $list1 = [];
    
    foreach ($this->the_list as $x) {
        if ($x % 2 != 0) {
            $list1[] = $x;
        }
    }
    
    return $list1;
}
function getOddNumbers() {
    $odd_numbers = [];
    
    foreach ($this->numbers as $number) {
        if (isOdd($number)) {
            $odd_numbers[] = $number;
        }
    }
    
    return $odd_numbers;
}

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

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

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

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

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

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

Не используйте слова, которые можно понять не так, как вы задумывали. Например, не называйте группу продуктов 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?

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

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

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

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

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

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

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

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

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

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

Заключение

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

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

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