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

Почему так важно именование?

«Как авторы кода, мы хотим, чтобы наш код был как можно более простым для понимания, беглым беглым просмотром, а не тщательным изучением. Не то что в академической статье, где твоя работа - выискивать смысл из бумаги ». - перефразировано из Чистого кода.

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

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

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

Почему именовать сложно?

Нейминг - это искусство, требующее хороших описательных навыков. Для некоторых это дается естественно, но большинство из нас с этим борется.

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

Как начать?

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

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

Не бойтесь рефакторинга и переименования файлов. Практика дает ... ну ... имена получше. «Худшее», что может случиться, - это то, что позже его снова поменяют. В любом случае вы научитесь и станете лучше.

Не заставляйте меня думать - значимые имена

Не заставляй меня думать! Это, вероятно, самое важное правило. Имена не должны заставлять нас задавать вопросы о значении предметов и ценностей. Кодировать достаточно сложно, не пытаясь понять смысл странного имени функции или запомнить содержимое какого-либо списка.
Для более подробного обсуждения см. «Чистый код» Роберта Мартина.

  • Выберите «Намерение раскрытия имен». Используйте как можно более четкий код. Если в переменной хранится последняя обновленная запись, назовите ее lastUpdatedRecord, а не просто record или даже lastRecord (последняя запись в файле ??).
  • Проводите значимые различия. Не делайте различий между похожими именами по орфографическим ошибкам или добавлением суффиксов к числам и шумовым словам, просто для того, чтобы удовлетворить компилятор. Это неинформативно. Например, ProductInfo vs ProductData Какого рода информация есть у ProductInfo, а у ProductData нет.
  • Добавьте содержательный контекст. Объем того, что вы называете, должен добавлять значимый контекст. Состояние переменной само по себе не имеет смысла. Поместите его в хорошо названный класс, например address.state или engine.state, а другие автоматически поймут ваше намерение.
    Наименее благоприятный, но иногда подходящий способ добавления контекста - это префикс или суффикс имени переменной - addressState.
    Каждая часть цепочки вызовов должна добавлять только новый контекст. Таким образом вы сможете сократить свои имена и сделать их достаточно значимыми.
  • Используйте доменные имена решения. Ваш код будет прочитан программистами, после чего вы можете и должны использовать термины информатики (jobQueue), названия шаблонов (AccountVisitor), названия алгоритмов, математические термины и т. Д.
  • Используйте имена проблемных доменов. Если объект больше связан с проблемным доменом, то, вероятно, у него есть подходящее имя в домене. Это поможет вам лучше ознакомиться с предметной областью и получить общий язык с клиентами. Дополнительное преимущество заключается в том, что концепции предметной области отделены от конкретного решения. Вы можете использовать строковый адрес и означать, что это адрес доставки. Но будет более понятным и надежным просто использовать `Address shippingAddress`.
// instead of
String state;
String streetAddress;
Int houseNumber;
// use
Address address
  • Не сокращайте. Говорите getWindow, а не getWin.

Концепции

Именование объектов - это абстрагирование и инкапсуляция поведения в рамках концепции.

  • Выберите одно слово для абстрактного концепции и придерживайтесь его. Вскоре у вас и вашей команды будет общий язык, и вы будете знать, чего ожидать от определенных имен. В чем разница между fetch и retrieve? выберите и используйте только один.
  • Однако не качайте и используйте одно и то же слово для разных вещей. Предположим, у вас есть два класса. Один класс создаст и добавит новый объект пользователя, используя метод add(). У второго класса есть метод, который вставляет параметр в коллекцию. Правило «Одно слово на концепцию» может ввести вас в заблуждение, назвав два метода add(), хотя на самом деле они имеют разную семантику.
    Другой пример использования имени для разных целей - это Бог-переменная temp, tmp, tmp1 ....
  • Избегайте ментального картирования. Это ОЧЕНЬ важно! Не заставляйте своих читателей мысленно переводить имена на что-то еще, что они знают. Вы должны даже назвать счетчики циклов, чтобы упростить задачу. Не будьте умным программистом, который демонстрирует свои умственные способности жонглировать. Будьте профессиональным программистом, который понимает, что Король ясности.
  • Используйте условные обозначения для общих операций. Например, как мне получить здесь Id?
worker.getId() 
candidate.id()
employee.id.get()
supervisor()
  • Точно используйте противоположности. Если вы можете open(), вы сможете close(); После start() вы должны stop()

Шум и плафон

Название должно быть максимально понятным и коротким. Шум заставляет читателя читать больше без каких-либо дополнительных преимуществ, кроме путаницы.

  • Не шумите. Что вы имеете в виду под ProductInfo? Чем он отличается от ProductData? Подобные суффиксы - это просто шум. Компилятор конфет. Они не добавляют четкого значения. Некоторые префиксы шума, такие как «the», «a» / «an», «all», могут использоваться для значимого различия, и в этом случае они не считаются шумом.
  • Избегайте комментариев. Хорошее имя в тысячу раз лучше комментария.
  • Оставьте устаревшие методы работы. Не будьте пещерным человеком, вместо этого используйте современную среду IDE с цветовым кодированием, документацией и инструментами для поиска ссылок.
    Скажи нет венгерской нотации. Тип в названии приведет к дезинформации при следующем рефакторинге и быстрой смене типа.
    Некоторые будут возражать против префикса членов с помощью m_ или просто _. Лично мне нравится "_" с дополнительным отличием от обычных переменных и параметров за невысокую стоимость одного символа. Нам не обязательно обо всем соглашаться ...
  • Остерегайтесь я для интерфейсной ловушки. Это может помочь и является условием для некоторых платформ. Просто не ставьте я перед конкретным классом, чтобы получить интерфейс. IDollar - не лучшее имя, чем Валюта. Carlo Pescio подробно останавливается на этом вопросе, а также на разнице между ООП и процедурой.
  • Не добавляйте произвольный контекст. Например, не используйте сокращенное название проекта в качестве префикса, например GSDMailingAddress. Это работает против вашей IDE (что происходит с автозаполнением, когда вы начинаете поиск метода с именем getSomethingImportant()?) И непригодным для использования в другом проекте.

Дезинформация

Иногда вызывается намеренно с самого начала, а иногда в течение обычного жизненного цикла разработки и рефакторинга. Так или иначе…

  • Избегайте связанных слов и сокращений, которые слишком связаны с другими значениями, чем то, которое мы имели в виду
    Избегайте использования типа в имени, например accountList. когда-нибудь кто-нибудь поменяет тип на hashSet, и имя потеряет смысл.
  • Избегайте небольших различий между длинными именами, например, используя o или l в качестве имен переменных, они слишком похожи на 0 и I.
  • Избегайте комментариев. Опять таки. код меняется, и никто не обновляет комментарии.

Человек-читатель

«Программы предназначены для чтения людьми и только случайно для выполнения компьютерами» - Дональд Кнут

  • Длина имени должна быть настолько длинной, насколько это необходимо для точной передачи смысла, однако она должна быть как можно короче для повышения удобочитаемости.
  • Предпочитайте удобочитаемость краткости - CanScrollHorizontally лучше, чем ScrollableX.
  • Сделайте код удобочитаемым, например Абзацы и предложения, и используйте грамматику как можно точнее.
  • Произносимые имена - вы должны иметь возможность обсуждать это, не выглядя как идиот. например plhmbuster.
  • Не будь милым или умным - смешные имена остаются понятными только до тех пор, пока вы и те, кто разделяет шутку, участвуете в проекте.
  • Избегайте кодирования и эмодзи. (я не должен даже упоминать об этом)
  • Используйте имена с возможностью поиска, чтобы помочь среде IDE, например, использовать константы для магических строк и чисел.
  • Избегайте похожих названий.
  • Избегайте ошибок в написании имен.

Заключение

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

Я что-то пропустил? Вы хотите, чтобы я знал, что вы думаете? Пожалуйста, сделай…