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

Автор оригинала: Daan
  • Перевод
Перед вами перевод статьи из блога 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 (или установить плагин), которая выделяет цветом переменные в зависимости от их области видимости.

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

Заключение


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

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

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

Комментарии 19

  • НЛО прилетело и опубликовало эту надпись здесь
      0

      Jetbrains это худо-бедно делают из коробки.

      +3

      Коротко о прочитанном — называйте переменные/методы/классы осмысленно, но не сильно коротко и не сильно длинно. Зачем целая статья?

        +8

        Я уж думал тут будет подсказка как найти синонимы для сущностей

          –1

          Несколько раз перечитал ваш комментарий. Пытался понять, причем тут БД, пока не понял, что речь не про entity и не про synonims для них.

            0

            А в БД есть entity? Ни разу вроде в доках не встречал, по крайней мере в SQL БД

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

          Не стоит забывать, что есть хорошие шрифты, решающие эту проблему.
            0
            Нет гарантии, что у людей, которые буду смотреть ваш код, окажется точно такой же шрифт и они не запутаются.
              +2
              last… least… latest..., а также opened… odds… over… (и так далее) вполне себе нормальные префиксы для переменных. Их запретить? Если кому-то не вломы постоянно гадать 0 vs o, «Я помочь не могу. Никто не может» (с)
              +3
              А еще мало-мальски опытный программист знает, что переменные не могут начинаться ни с 0, ни с 1.

              Про запрет на префикс m_ тоже странный совет.

              void CObjectsContainer::Set( const vector<OBJECT> & objectList )
              {
                 m_objectList = objectList;
              }
              


              Сразу ясно что происходит, что где содержится и для чего используется.
                0

                Про m_ может актуально для некоторых языков, где есть неявные this, но это практика переносится и в другие языки, где исключительно явная. И там она лишняя

                  0
                  В качестве итога можно сказать следующее:
                  — Есть языки, где подобная практика излишняя: действительно, смотрится очень куцо:
                  this->m_Value = Value;

                  — Есть языки, где отсутствие префиксов явно вредит читаемости и пониманию кода (см. пример выше).

                  Но автор решил, что подобное надо искоренять. Тег php стоит, конечно, но стоило бы упомянуть явно, что речь идет о практиках программирования в php.
                0

                В большинстве известніх мне языков имя переменной или другой сущности не может начинаться с цифры, так что в них точно проблема надуманная. Это даже если не вспоминать про автодополнение IDE или мощного редактора. С другой стороны, один хорошо знакомый разработчик практически никогда не пишет переменные руками, кроме первого раза — копипастит. И на его таски почти никогда не бывает багов, кроме тех, что по факту являются уточнением требований, когда у QA другое мнение, каким должно быть неописанное или недостаточно однозначно описанное в таске поведение. Очень щепетильное отношение к работе, и такой копипаст — один из аспектов общего подхода. Иногда даже раздражает, когда в паре работаем, ну вот переменная из трёх букв, которую сам только что написал, иде автодополение абсолютно точно не предлагает, но нет, "копировать-вставить"

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

                OfficeLocation location = getOfficeLocation();

                О, нет, что здесь происходит? Что такое ноль-ффис? Что такое один-ноль-кейшн?

                  +1
                  А теперь посмотрите на функцию getOddNumbers. Увидели, что она делает то же самое, что и getList?
                  Последнее время начал замечать что для разработки очень большого класса с множеством отдельных сущностей есть смысл писать NumbersGet, ListGet. На тот случай если у вас кроме Get есть еще толпа глаголов, особенно когда каждая сущность имеет свои уникальные глаголы. Лучше конечно разделить эти сущности. Но при первом наброске чисто визуально проще искать не getList, setList, putNum, delNum, а именно с начало найти Num, List и подом действие. Выглядит странно, но мне нравиться. :)
                    0

                    Вы изобрели венгерскую нотацию? :)

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

                    А если они заканчиваются на них, то это конечно Ок. )
                      0

                      Или в середине содержат )

                      +1
                      Я согласен с Gorthauer87. Наверное как и многие, я ожидал увидеть здесь больше методики чем советов.

                      Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                      Самое читаемое