Почему вы должны прилагать усилия и заботиться о названии вещей
Правильное обозначение вещей в коде чрезвычайно важно, потому что оно:
- Улучшает общую читаемость
- Снижает когнитивную нагрузку при понимании концепций.
- Помогает другим понять и ваш код - вы не единственный участник!
- Из этого следует… чем легче это понять другим, тем быстрее работать и меньше шансов вызвать ошибки из-за непонимания и т. Д.
Код должен читаться как рассказ, а не детективный роман
- Дэниал Маркхэм
Представьте, что вы открываете новостную статью, которая привлекла ваше внимание, под названием «Натуральная вакцина против Covid со 100% успехом, развертывание за 2 недели», и это то, что начал автор:
Группа ученых работает над естественно активированным антителом, обнаруженным в организме человека, путем сплайсинга мРНК с клареденом fnt6C8, который естественным образом образуется в биоклеточной стенке мембран эндотелиальных клеток сосудов.
… Не знаю, как вы, но меня это оставит в замешательстве. В названии говорилось все, но начальное содержание представляло собой загадочную загадку. Это могло иметь смысл для репортера на момент написания: когда они провели все свои исследования и были в «зоне» набирая все свои знания для статьи.
Коммуникация находится на переднем крае работы репортеров. Они должны избавиться от собственных предубеждений и использовать термины, которые могут быть простыми, межкультурными и легко понятными практически для всех.
Как кодировщики, мы пишем структурированные тела текста, которые должны быть усвоены и поняты участниками, кроме нас. При написании кода есть большая свобода творчества. И это зависит от вашего родного языка, культуры и общего происхождения. Поэтому чрезвычайно важно учитывать эти различия при написании кода.
Часто мы (программисты) не всегда думаем, что другие читают наш код. Иногда мы это делаем, но проскальзываем в «зону» и выкладываем какой-нибудь «блестящий» код, который, возможно, мы сможем понять. Бьюсь об заклад, ваше будущее, вероятно, не будет.
В информатике есть две серьезные проблемы: недействительность кеша, присвоение имен объектам и ошибки с уменьшением на 1.
(Мартин Фаулер изначально хорошо процитировал 2 сложных момента в информатике)
При установлении нового термина для чего-то в кодовой базе: лучше всего достичь консенсуса, это может появиться на этапе проверки кода. Но если это принципиально новая концепция, лучше всего обсудить свои идеи с командой перед написанием кода.
Итак, есть ли какие-то правила для именования вещей…? да, пожалуйста, прочтите ...
Присвоение имен вещам представляет собой проблему технологического программирования, на самом деле это проблема социализационного кодирования.
- Дэниал Маркхэм
Методические рекомендации
Имена в коде должны передавать намерения.
Будьте согласованы с именами: избегайте незначительных вариантов. тонкости с разными названиями одного и того же предмета могут вызвать большую путаницу, особенно для новичков в кодовой базе.
У Microsoft есть несколько хороших рекомендаций для семейства языков dotnet (например, C #):
- 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
У каждого языка будут свои стандартные правила. На мой взгляд, лучше всего придерживаться самых официальных правил, насколько это возможно, а не пользовательских предпочтений, чтобы люди, перемещающиеся между компаниями / кодовыми базами, могли легко и свободно делать это, не смешивая стандарты.
Примечание. Не путайте правила стиля с правилами именования. Стилизация / форматирование полностью отличается от именования вещей.
Несколько простых примеров
- Класс с именем
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