15 советов для лучшего нейминга в коде

  • 30 марта, 14:02
  • 3994
  • 0

Имена в коде везде. Мы называем наши классы, переменные, наши функции, аргументы и многое другое. Стоит убедиться, что вы делаете это хорошо. Вот 20 советов, которые помогут вам улучшить нейминг в вашем коде.

15 советов для лучшего нейминга в коде

1. Используйте намерение в имени

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

2. Не бойтесь тратить время на выбор имени

Вы не должны чувствовать вину за то, что долго выбираете имя, которое, по вашему мнению, является достаточно "описательным". Каждый, кто будет читать ваш код в будущем (включая вас), получит от этого только выгоду. Кроме того, придумывание точного названия часто поможет вам прояснить структуру модуля. Хорошее именование требует времени, но в долгосрочной перспективе сэкономит больше, чем нужно.

3. Рефакторинг имен

Если вы придумали более подходящее имя в процессе разработки, смело меняйте его. Современные IDE делают рефакторинг имен невероятно простым. Нередко менять имя стоит только для того, чтобы благоприятная реструктуризация кода стала очевидной.

4. Избегайте попсовых слов 

Слова типа Manager, Processor, Data или Info и являются синонимами «Я не знаю , как назвать это». Если вы обнаружите, что хотите использовать одно из этих слов - лучше не стоит.

5. Остерегайтесь трудных названий классов / функций

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

6. Имена классов

Классы должны иметь существительные  имена, как Customer, WikiPage, Account и AddressParser. При использовании наследования суперклассы должны иметь короткие и четкие имена. Подклассы должны иметь более длинные имена, содержащие прилагательные, которые описывают, как этот класс отличается от своего суперкласса, например, SavingsAccount происходит от Account.

7. Имена переменных

Переменные часто содержат экземпляры классов, поэтому они также должны быть существительными. Они часто происходят от названия класса, на который они ссылаются. Булевы переменные должны быть записаны как предикаты, например isEmpty или isTerminated так, чтобы они хорошо читались в операторах if.

8. Названия методов

Методы должны иметь названия глагола или фразы глагола, такие как postPayment(), deletePage()или save(). Accessors и мутаторы должны иметь префикс get и set соответственно. Методы, которые возвращают логическое значение, должны начинаться с «is», например, isPostable()так, чтобы они хорошо читались в операторах if.

9. Размер области к длине имени переменной

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

10. Размер области к длине имени метода / класса

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

11. Избегайте одного и того же термина для двух разных понятий

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

Например, мы могли бы использовать add() метод в нескольких классах, чтобы обозначить создание нового значения путем добавления или объединения двух существующих значений. Если затем мы добавим метод add в класс, в котором он используется для добавления одного параметра в коллекцию, это вызовет проблемы, так как семантика различна. Лучший термин для этого нового метода будет insert().

12. Используйте "правильные" технические термины

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

13. Добавьте содержательный контекст

Большинство имен сами по себе не имеют смысла и должны быть помещены в контекст (класс / функция / пространство имен), чтобы читатель мог понять, на что они ссылаются. В некоторых случаях может потребоваться добавить префикс имен для добавления некоторого контекста. Например, если у нас есть целый ряд переменных, которые используются для представления адреса firstName, lastName, street, houseNumber, city, stateи zip. Если вы только что увидели state переменную, было бы сложно автоматически определить, на что она ссылается, лучшим решением будет инкапсуляция переменных в Address классе.

14. Не добавляйте контекст в короткие имена

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

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

Не оставляйте ложные подсказки, которые дезинформируют относительно значения кода. Если у вас есть переменная accountList, которая на самом деле содержит массив, это может привести к ложным выводам. Имя должно говорить, что оно означает, и означать, что оно говорит.


Теги: код
0 комментариев
Сортировка:
Добавить комментарий