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

Правильное обозначение вещей в коде чрезвычайно важно, потому что оно:

  • Улучшает общую читаемость
  • Снижает когнитивную нагрузку при понимании концепций.
  • Помогает другим понять и ваш код - вы не единственный участник!
  • Из этого следует… чем легче это понять другим, тем быстрее работать и меньше шансов вызвать ошибки из-за непонимания и т. Д.

Код должен читаться как рассказ, а не детективный роман
- Дэниал Маркхэм

Представьте, что вы открываете новостную статью, которая привлекла ваше внимание, под названием «Натуральная вакцина против Covid со 100% успехом, развертывание за 2 недели», и это то, что начал автор:

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

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

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

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

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

В информатике есть две серьезные проблемы: недействительность кеша, присвоение имен объектам и ошибки с уменьшением на 1.

(Мартин Фаулер изначально хорошо процитировал 2 сложных момента в информатике)

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

Итак, есть ли какие-то правила для именования вещей…? да, пожалуйста, прочтите ...

Присвоение имен вещам представляет собой проблему технологического программирования, на самом деле это проблема социализационного кодирования.
- Дэниал Маркхэм

Методические рекомендации

Имена в коде должны передавать намерения.

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

У Microsoft есть несколько хороших рекомендаций для семейства языков dotnet (например, C #):

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

Примечание. Не путайте правила стиля с правилами именования. Стилизация / форматирование полностью отличается от именования вещей.

Несколько простых примеров

  • Класс с именем class HealthCheck { … }, лучше было бы называть HealthChecker (изменение глагола на существительное)
  • class DeviceTypeBusiness: почему «бизнес»? действительно ли вашему коду нужно знать, какой «слой» он находится в архитектуре, добавляя суффиксы к именам? Люди, не знакомые с эталонной архитектурой кодовой базы, могут просто ломать голову над тем, что означает «бизнес».
  • Если вы отделяете классы данных от классов, содержащих логику (довольно часто), попробуйте использовать обычное решение для разделения классов данных (сущностей) и классов бизнес-логики / логики домена (интерфейсы служб).
    Пример: рассмотрите возможность использования чего-то вроде ConsumerRepository вместо а) Consumer или б) Consumers. а) звучит как единое целое, и б) кажется немного двусмысленным, поскольку звучит как общая коллекция с поддержкой памяти. Я бы зарезервировал Consumer в качестве имени класса данных.
  • Избегайте чрезмерного использования временных переменных с короткими руками, такими как x, y, z, особенно с вложенной логикой. например вместо
    reports.Where(x => x.IsPublished && x.References.Any(y => y.Date > Today));
    Вам может понадобиться:
    reports.Where(report => report.IsPublished && report.References.Any(reference => reference.Date > Today));
  • Избегайте сокращенных обозначений идентификаторов в теле методов:
    var psn = _personFactory.Create();
    Пожалуйста, не поленитесь и сделайте следующее:
    var person = _personFactory.Create();
  • Избегайте общих имен методов: будьте наглядными. Я буквально начинаю с объяснения того, что делает метод, и, если это слишком долго, возможно, метод делает слишком много, и я реорганизовываю его в более мелкие методы (SRP).
    Например, это одно из моих питомцев, которые я ненавижу:
    Validate(person);
    Что он делает? выкинуть, если человек инвалид? Или еще что-то?
    Если все-таки выкинет, как насчет ThrowIfPersonInvalid(person);? Или, может быть, даже лучше, не полагаться на поток исключений и позволить вызывающей стороне решать: var errors = GetPersonDataValidationErrors(person);
  • Точно так же, пожалуйста, не вводите в заблуждение, что делают функции или классы. Если за кодом скрыто поведение, которое имя не передает, значит, вы неправильно назвали его и написали загадочный код.

Пожалуйста, пожалуйста, не забудьте…

Код для людей, а не компьютеров

Позаимствуйте технику из циклов Red Green Refactor в TDD - если вы не хотите следовать TDD

Если вы не подписаны на TDD, вы все равно можете воспользоваться некоторыми из замечательных техник TDD: выполнив последний цикл рефакторинга. TDD - это непрерывная серия циклов рефакторинга красный-зеленый: напишите провальный тест, дайте ему пройти, не беспокоясь о чистом читаемом коде, затем выполните рефакторинг: сосредоточьтесь на том, чтобы сделать код чистым. Если вы проводите вдумчивое тестирование (или, осмелюсь сказать, без автоматического тестирования!), Вы можете просто провести рефакторинг в конце своих циклов (возможно, это всего лишь один большой цикл, в котором вы рефакторируете в конце, прежде чем отправлять PR. или нажмите в систему управления версиями). Наденьте шляпу «чистого кодировщика» отдельно от шляпы решения проблем, чтобы не перепутать их. Таким образом ваш код станет намного, намного чище и проще.

Что вы можете сделать сейчас и дальнейшие чтения

Прочтите рекомендации Microsoft по именованию (это краткое руководство)

  • Https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/general-naming-conventions
  • Https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/names-of-classes-structs-and-interfaces
  • Если во время проверки кода имя не имеет для вас смысла, предложите альтернативу.
  • Рефакторинг: переименование большинства вещей чрезвычайно низко и очень просто. Особенно со всеми инструментами рефакторинга, выпущенными в настоящее время.
  • Рассмотрим TDD: даже если вы напишете тесты позже, сделайте рефакторинг в конце всего тестирования, чтобы сделать код более читабельным.
  • Будьте особенно осторожны при переименовании веб-API / контрактов или общедоступных интерфейсов / классов в общих библиотеках: они могут вызвать критические изменения.
  • Подумайте о том, чтобы послушать подкаст чистых кодеров о присвоении имен вещам: CC 009: Присвоение имен вещам с Дэниэлом Маркхэмом | Devchat.tv