Имена везде в программном обеспечении. Мы называем наши переменные, наши функции, наши аргументы, классы и пакеты. Мы даем имена нашим исходным файлам и каталогам, которые их содержат. Мы называем наши jar-файлы, war-файлы и ear-файлы. Мы называем, и называем, и называем. Поскольку мы делаем так много, нам лучше делать это хорошо. Ниже приведены несколько простых правил создания хороших имен.
Именование:
Выбор хороших имен требует времени, но экономит больше, чем нужно. Так что берегите свои имена и меняйте их, когда найдете лучшие. Все, кто читает ваш код (включая вас), будут счастливы, если вы это сделаете.
Имя переменной, функции или класса должно ответить на все важные вопросы. Он должен рассказать вам, почему он существует, для чего он нужен и как он используется. Если имя требует комментария, то имя не раскрывает его намерения.
Шумные слова - бессмысленное различие. Представьте, что у вас есть класс Product. Если у вас есть другой, называемый ProductInfo или ProductData, вы изменили имена, но не означают, что они по-разному. Информация и Данные - это неразборчивые шумовые слова, такие как a, an и the.
Обратите внимание, что нет ничего плохого в использовании соглашений о префиксах, таких как a и, пока они проводят значимое различие. Например, вы можете использовать a для всех локальных переменных и для всех аргументов функции.3 Проблема возникает, когда вы решаете вызвать переменную theZork, потому что у вас уже есть другая переменная с именем zork.
Используйте произносимые имена
Используйте имена с возможностью поиска:
Избегайте кодирования
Префикс участника
Интерфейс и реализация:
Например, скажем, вы строите АБСТРАКТНЫЙ ЗАВОД для создания форм. Эта фабрика будет интерфейсом и будет реализована конкретным классом. Как их назвать? IShapeFactory и ShapeFactory? Предыдущее I, столь часто встречающееся в сегодняшних старых пачках, в лучшем случае отвлекает, а в худшем - слишком много информации. Я не хочу, чтобы мои пользователи знали, что я передаю им интерфейс. Я просто хочу, чтобы они знали, что это ShapeFactory. Поэтому, если мне нужно кодировать интерфейс или реализацию, я выбираю реализацию. Назвать его ShapeFactoryImp или даже отвратительным CShapeFactory предпочтительнее, чем кодировать интерфейс.
Избегайте ментального картирования
Читателям не нужно мысленно переводить ваши имена на уже известные им имена. Эта проблема обычно возникает из-за выбора не использовать ни термины проблемной области, ни термины области решения.
Это проблема с однобуквенными именами переменных. Конечно, счетчик цикла может называться i, j или k (но никогда не l!), Если его область действия очень мала и никакие другие имена не могут конфликтовать с ним. Это потому, что эти однобуквенные имена для счетчиков циклов являются традиционными. Однако в большинстве других контекстов однобуквенное имя - плохой выбор; это просто заполнитель, который читатель должен мысленно сопоставить с действительной концепцией. Не может быть худшей причины для использования имени c, чем то, что a и b уже были взяты.
В целом программисты довольно умные люди. Умные люди иногда любят блеснуть своим умом, демонстрируя свои умственные способности жонглировать. В конце концов, если вы можете надежно помнить, что r - это версия URL-адреса в нижнем регистре с удаленными хостом и схемой, то вы, очевидно, должны быть очень умными.
Одно из различий между умным программистом и профессиональным программистом состоит в том, что профессионал понимает, что ясность - главное. Профессионалы используют свои способности во благо и пишут код, понятный другим.
Имя класса:
Классы и объекты должны иметь имена существительных или существительных фраз, такие как Customer, WikiPage, Account и AddressParser. Избегайте таких слов, как «Менеджер», «Процессор», «Данные» или «Информация» в названии класса. Имя класса не должно быть глаголом.
Имена методов:
Методы должны иметь глагольные названия или глагольные фразы, такие как postPayment, deletePage или save.
Не будь милым
Если имена слишком умные, они запомнятся только людям, разделяющим авторское чувство юмора, и только до тех пор, пока эти люди помнят шутку. Будут ли они знать, что должна делать функция HolyHandGrenade? Конечно, это мило, но, возможно, в этом случае лучше использовать DeleteItems. Выбирайте ясность, а не развлекательную ценность.
Выберите одно слово для концепции
Выберите одно слово для одного абстрактного понятия и придерживайтесь его. Например, сложно использовать методы fetch, retrieve и get как эквивалентные методы разных классов. Как вы запомните, какое имя метода соответствует какому классу? К сожалению, вам часто приходится вспоминать, какая компания, группа или отдельное лицо написала библиотеку или класс, чтобы запомнить, какой термин использовался. В противном случае вы потратите очень много времени на просмотр заголовков и предыдущих примеров кода.
Не качайте
Избегайте использования одного и того же слова в двух целях. Использование одного и того же термина для двух разных идей - это, по сути, игра слов.
Если вы будете следовать правилу «одно слово на концепцию», вы можете получить много классов, например, у которых есть метод добавления. Пока списки параметров и возвращаемые значения различных методов добавления семантически эквивалентны, все в порядке.
Однако кто-то может решить использовать слово «добавить» для «согласованности», когда он или она на самом деле не добавляет в том же смысле. Допустим, у нас есть много классов, в которых add создаст новое значение путем добавления или объединения двух существующих значений. Теперь предположим, что мы пишем новый класс, у которого есть метод, который помещает его единственный параметр в коллекцию. Следует ли называть этот метод добавить? Это может показаться последовательным, потому что у нас так много других методов добавления, но в этом случае семантика другая, поэтому вместо этого мы должны использовать имя l ike insert или append. Вызвать новый метод add было бы каламбуром.
Добавьте содержательный контекст
Представьте, что у вас есть переменные с именами firstName, lastName, street, houseNumber, city, state и zipcode. Взятые вместе, довольно ясно, что они образуют адрес. Но что, если вы только что увидели, что переменная состояния используется в методе отдельно? Вы бы автоматически сделали вывод, что это часть адреса?
Вы можете добавить контекст, используя префиксы: addrFirstName, addrLastName, addrState и т. Д. По крайней мере, читатели поймут, что эти переменные являются частью более крупной структуры. Конечно, лучшее решение - создать класс с именем Address. Тогда даже компилятор знает, что переменные принадлежат более крупной концепции.
Рассмотрим метод, описанный ниже. Нужен ли переменным более значимый контекст? Имя функции предоставляет только часть контекста; все остальное алгоритм обеспечивает. Прочитав функцию, вы увидите, что три переменные, число, глагол и pluralModifier, являются частью сообщения «предполагаемая статистика». К сожалению, контекст должен быть выведен. Когда вы впервые смотрите на метод, значения переменных непрозрачны.
Функция слишком длинная, и везде используются переменные. Чтобы разделить функцию на более мелкие части, нам нужно создать класс GuessStatisticsMessage и создать три поля переменных этого класса. Это обеспечивает четкий контекст для трех переменных. Они окончательно являются частью GuessStatisticsMessage. Улучшение контекста также позволяет сделать алгоритм намного чище, разбив его на множество более мелких функций.
