Чистый код. Конспект. Глава 2. Содержательные имена

Продолжаем читать Мартина. И сегодня очень полезная глава про имена. Думаю, для опытных разработчиков она бесполезна, но вот для начинающих — самое то. Я помню, что на первых лекциях по Java сама называла методы и переменные в стиле 'a' и 'method1' и не понимала, что не нравится преподавателям.

Сегодня будет много текста, так что готовьтесь. :)

Заметки:

1. Имя должно рассказывать, почему переменная/метод/класс существует,что она делает и как используется.
2. Если к имени переменной нужно добавить комментарий, то это плохое имя. Например: val days // дни недели. Лучше сразу назвать val daysOfTheWeek. И в коде, когда встретите daysOfTheWeek сразу будете знать, за что отвечает переменная. Это намного удобней, чем переходить к моменту создания и искать комментарий.
3. Содержательные имена позволяют быстро читать код. Не нужно будет постоянно держать в голове, для чего нужна переменная, или периодически возвращаться к началу, чтобы посмотреть комментарии.
4. Не используйте имена, которые могут ввести в заблуждение. Например val hp = 12. Что означает hp? Даже если кажется, что это крутое сокращение для гипотенузы — это не так. За лишние буквы нет штрафов, так что лучше не сокращать.
5. Не используйте слово List и похожие слова, если хранение отличается. Например, при встрече catsList будет странно увидеть, что там не лист, а сет котов. Или массив котов. Или мапа. Лучше назвать просто cats или catsGroup.
6. Не используйте похожие имена, где нужно много времени, чтобы понять разницу. Например: ABCDXYAZControllerForAwesomeHandlingOfStrings и ABCDYXAZControllerForAwesomeStorageOfStrings.
7. Не используйте буквы l и o. Первая причина — они ни о чем не говорят. Вторая — сложно понять, что это вообще за буква — L маленькая или i большая? Или вообще единица? А буква о похожа на нолик.
8. Бывает, что имя уже занято, но нужно создать временную переменную с таким же именем. Есть соблазн написать неправильно. Потом приходит новый разработчик, видит грамматическую ошибку — исправляет и программа внезапно перестает собираться. Не делайте так.
9. Давайте осмысленные имена для разных объектов, чтобы была понятна разница. Например Cat и CatObject. AccountData и Account. Чем они отличаются?
10. Используйте имена, которые можно произнести. При обсуждении задачи часто приходится говорить про всякие классы и методы. Хочется, чтобы это было легко и непринужденно, а не выговаривание каких-то mhms.
11. Выбирайте имена, удобные для поиска. Число 7 сложно найти. Константу DAYS_OF_WEEK легко. А еще сразу понятно, что означает число 7.
12. Однобуквенные имена могут использоваться ТОЛЬКО для локальных переменных в коротких методах. Длина имени соответствует его области видимости. Для циклов часто используют просто for(i in cats). Но даже тут я предпочитаю использовать осмысленное имя. for(cat in cats) намного понятней.
13. Венгерская запись устарела (это когда в имени указываем тип). Раньше это были подсказки для программистов, но сейчас ошибку с типизацией любая ide может выявить до начала компиляции. Венгерская запись просто затрудняет чтение.
14. Префиксы в стиле m_ тоже устарели. Мы все равно читаем код, игнорируя их, и обращая внимание только на содержание. Кстати, часто встречаю такой префикс в различных библиотеках. Выглядит странно.
15. Для интерфейсов пишем CatFactory, а не ICatFactory. Когда мы используем ICatFactory, то нам не надо знать, что это интерфейс. Бесполезная информация. Лучше в реализации добавить постфикс Impl— ShapeFactoryImpl.
16. Имена классов — существительные и их комбинации: Cat, WikiPage и т.п.
17. Имена методов — глаголы или глагольные сочетания. postAnswer, openPage и т.п.. Метод для записи информации начинается с set. Методы для получения какой-то информации начинается с get.
18. При перегрузке конструктора лучше использовать статические методы-фабрики с именами. Просто сравните: Complex.FromRealName(23.0) и new Complex(23.0). Первый намного понятней.
19. Оставьте свое чувство юмора при себе. Никаких eatMyShorts() и прочих шуток в названиях. Аналогично про расизм, сексизм и т.п.
20. Выберите концепцию и придерживайтесь её. Почему где-то Controller, а где-то Manager? Где-то get, а где-то fetch? Что нам использовать и когда?
21. Не используйте одно название для разной логики. Если вы везде используете add для конкатенации двух слов, то не используйте add для метода с добавлением значения в список. Лучше insert.
22. Не бойтесь давать технические имена. Мы все разработчики и поймем, если в названии будет, например, имя алгоритма или паттерна.
23. Имена должны быть в контексте. Имена firstName, lastName, houseNumber, street, state, zipcode вместе образуют адрес. Но что вы подумаете, если встретите state в коде отдельно от адреса? Сложно понять, что это часть адреса. Можно добавить префикс и сделать addressState, но лучше поместить переменные внутрь нового класса Address и использовать с ним.
24. Не надо делать избыточный контекст. Например, BankCustomerAddress. Всегда думайте, что приложение может расширяться и дальше будет использоваться не для банка, а, например, для клиентов авиакомпании. BankCustomerAddress уже не будет подходить для любителей летать. Лучше сразу сделать просто CustomerAddress.
25. Не бойтесь брать инициативу в свои руки и переименовывать, если видите лучшее название. Коллеги не будут ругать, а скажут спасибо. Я сначала очень боялась что-то переименовать. Вдруг, это какой-то мега-важный метод. Но оказалось, что никто не помнит имена методов и главное, чтобы он хорошо читался.