Многие разработчики проводят обзоры кода своих коллег и коллег, и всем известно, что именование является одним из наиболее важных аспектов высококачественного кода.
Давайте поговорим об именовании: почему оно так важно, какие имена хороши и каких принципов следует придерживаться, чтобы создавать отличный код.
Почему нейминг так важен
Хорошие имена классов, переменных и функций важны, потому что они отражают идею, цель и причину их создания. Если в коде есть элементы с непонятными именами, он имеет запах кода, а это показатель общего низкого качества кода.
Если соблюдаются все принципы и элементы действительно отражают свое назначение, то можно легко определить места для улучшения кода или потенциальных архитектурных изменений или улучшений.
Какие имена хороши
Каждая функция, класс или переменная должны отражать в названии основную цель их создания. Как правило, класс или структура представляет собой объект, функция представляет собой действие, а переменная представляет собой состояние чего-либо. Рассмотрим принципы именования.
Классы/Структуры/Перечисления/Протоколы/Интерфейсы
Имя можно выбрать по следующему шаблону:
[PurposeOfTheUnit][UnitName] или [UnitName].
Пример: Point, UserDataManager, DataStorage, UserProfile и т. д.
Функции
Шаблон для функций такой:
[Действие][С какими входными параметрами][Другое значимое дополнение]. Важно: названия функций должны быть удобными для возврата результата.
Например: calculateDelta(…) -> [Результат расчета], updateView(), refreshPageIfNeeded()
Отсутствие [Действия] является грубая ошибка, потому что основная цель любой функции — совершить действие.
Переменные
Переменные должны иметь достаточно хорошее описание своего назначения в текущем контексте (член класса или локальная функциональная переменная). Конечно, есть группа имен переменных, которые приняты во всей индустрии разработки ПО на протяжении многих лет (i, k, j, id и т. д.) и могут быть легко использованы. Также иногда допустимы короткие имена, если они находятся в правильном контексте (например, sw как юго-западная координата в функции с вычислением расстояния)
Пример: i, eventCounter, viewState
Какие имена плохие
Следуя одному из моих любимых принципов: используйте шаблоны и избегайте анти-шаблонов, нужно поговорить о плохом именовании. Это наиболее частые случаи:
- бессмысленные имена/непонятные имена
событие. Не понятно, что это за какое-то событие или состояние, или какое-то действие с событием - неправильные уровни абстракции
Имена следует выбирать в соответствии с их уровнем абстракции. Например, если у вас есть класс с именем UnitsStorage, в нем должны быть функции, работающие с модулями, но не с конкретными типами модулей. - имена функций, которые не отражают фактическое действие(я) функции
calculateDelta(…), которая фактически выполняет внутреннюю печать. Думаю, это критический момент, потому что правильное название функции может указывать на следование SRP (принцип единой ответственности).
Какие имена неудобны
Имена, которые не очень хорошо отражают ситуацию. Например, нет необходимости вызывать переменную iteractionNumber в цикле for, в 99% случаев достаточно i. И наоборот: eC не полностью отражает идею eventCounter на уровне класса.
Советы и рекомендации
- Следуйте руководствам по стилю кода для используемого вами языка (swift, java, c# и т. д.)
- Предпочитайте ясность краткости
- Отразите идею в названии
- Примените идеи из этих статей
Любые вопросы приветствуются!
