Важность наименования

Кто когда-либо сталкивался с именем переменной `obj`, или` item`, или `num`, или` str`, или `ret`, или` val`, или `test`, или` count` при чтении кода?

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

Почему это имеет значение?

Когда мы рассматриваем аудиторию исходного кода в компьютерном программировании, основная аудитория очевидна для всех программистов. Некоторый компьютерный процесс будет анализировать код, чтобы превратить его в желаемую функциональность / отображение / функцию / и т. Д. - чтобы изменить его на единицы и нули, которые в конечном итоге повлияют либо на некоторые данные, либо на отображение, либо на то и другое, так что чья-то жизнь может быть улучшена в каким-то образом. Программа с каждой переменной / классом / объектом, названным как `w48293` (некоторая буква, за которой следует некоторое число), могла бы дать такой же функциональный результат для этой аудитории, что и программа с отличным наименованием.

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

Затраты и экономия за счет качества наименования

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

Плохо продуманные имена, которые сразу приходят в голову, могут показаться самым простым или очевидным выбором в то время, когда они созданы, но, пожалуйста, уделите несколько дополнительных минут, чтобы тщательно продумать, как назвать каждую вещь, чтобы это можно понять с точки зрения стороннего наблюдателя. Очень легко попасть в ловушку, будучи настолько погруженным в проект или концепцию, что названия, которые мы создаем, имеют для нас смысл в то время, но не будут иметь смысла для кого-то, кто видит программу впервые. Мы не хотим, чтобы имена требовали исследования контекста или каких-либо глубоких знаний о продукте (я-работал-над-этим-два-месяца-прямо-так-я-точно-знаю-что -this-acronym-means), особенно когда небольшая дополнительная мысль теперь может преодолеть это.

Когда мы читаем имя в программировании, а оно недостаточно конкретное или ясное, чтобы описать ценность или сущность, которые оно представляет, это заставляет нас исследовать дальше. Мы вынуждены искать контекст внутри блока кода, а иногда даже дальше для любого или всех случаев использования этого имени. Мы можем просматривать ближайшие комментарии, но комментарии требуют обслуживания и могут стать устаревшими, бесполезными или даже некорректными, если их не поддерживать должным образом. Иногда нам нужно пойти еще дальше - найти связанные сущности на основе части имени. Если некоторые из этих связанных имен имеют сокращения / несоответствия / и т. Д., Поиск может дать неполные результаты, оставляя нам высокую вероятность совершения ошибок во время рефакторинга, или дополнительное время, потраченное на поиск каждой связанной сущности вручную, и дополнительную неопределенность в отношении того, что могло быть упущено. И если соглашения об именах, такие как camelCase, snake_case или PascalCase, не применяются последовательно в языке и в вашей организации программирования, становится еще труднее найти, классифицировать, сгруппировать, рефакторинг, улучшить и т. Д. Какой вывод из этого можно сделать? Поддержка кода с плохим именованием приводит к большему количеству проблем и расходов, особенно в долгосрочной перспективе, по сравнению с поддержкой кода с хорошим именованием.

Самый простой способ улучшить практику именования при кодировании - просто уделить несколько дополнительных минут тому, чтобы критически рассмотреть каждое имя, которое вы создаете. Можно ли истолковать это имя иначе, чем я задумал? Полностью ли это имя описывает значение представляемой ценности или сущности? Точно ли это имя функции передает то, что она делает? Какие значения будет содержать эта переменная в разные моменты времени и точно ли это имя для всех них? Согласуется ли это имя с другими названиями, используемыми в продукте / языке / организации / отрасли?

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

Синтаксис и общие рекомендации:

Используйте соглашения об именах используемого языка программирования. Использование заглавных букв, синтаксис нескольких слов и общие языковые соглашения для различных элементов программирования, таких как классы, интерфейсы, свойства, константы и т. д., должны соблюдаться повсюду. кроме случаев, когда стандарты кодирования вашей организации намеренно различаются. Рефакторинг: примените стандартный языковой регистр и используйте инструменты проверки кода для конкретного языка, чтобы обеспечить его соблюдение.
Избегайте различать идентификаторы с помощью числовых суффиксов. Числовые суффиксы не добавляют значимого различия между переменными с одинаковым базовым именем и разными числами в конце. Рефакторинг: используйте дополнительные или другие слова в именах, чтобы различать значения.
Полностью составляйте слова из словаря с правильным написанием. Сокращенные или неправильно написанные слова, даже если они используются неоднократно, вызывают путаницу, двусмысленность и непоследовательность. Они также затрудняют поиск употребления определенных слов. Аббревиатуры также могут интерпретироваться как слова, отличные от предполагаемых во многих случаях (например, `mod` - это может означать модуль, модуль, режим, модальный, модель, модем или модальность). Ввод полного слова, написанного правильно, делает его доступным для поиска и делает исходное намерение явным, вместо того, чтобы заставлять читателей интерпретировать двусмысленное значение для себя (зря потраченное время). Рефакторинг: исправьте написание слов с ошибками и замените сокращенные слова на полные слова. Делайте исключения для однозначных и понятных значений, таких как идентификатор, а также для задокументированных аббревиатур и сокращений для конкретных доменов, если они не являются двусмысленными.
Назовите значения констант. Для безымянных констант, которые включают магические числа, каждая обычно вызывает мысленный ответ: «Почему это есть и что это означает?» (очередная трата времени для читателей). Рефакторинг: дайте каждому постоянному значению имя, в частности, для того, что оно представляет, а не только для значения, которое оно содержит (WaterBoilingPointCelcius вместо 100 илиOneHundred; DaysPerWeek вместо 7 или Seven).
Поместите квалификаторы как суффиксы, если существует несколько вариантов. Это естественным образом группирует похожие имена вместе, повышая эффективность программирования с использованием этих имен. Рефакторинг: переместите квалификационную формулировку в конец имен (AgeMaximum AgeMinimum AgeAverage).

Словарный запас:

Опишите значение. Один из наиболее важных способов обеспечить хорошее именование - это использовать имена, концептуально описывающие то, что представляет собой идентификатор. Избегайте бездумных / бессмысленных имен (foo blah temp). Рефакторинг: опишите, что представляет собой идентификатор.
Выберите формулировку, которая имеет одно конкретное ясное значение. Подумайте, не слишком ли расплывчата формулировка; предпочитаю более конкретную формулировку. Подумайте, может ли формулировка привести к множественному толкованию; предпочитаю формулировку, которая сводит к минимуму возможность неправильного толкования. Рефакторинг: замените расплывчатые формулировки (данные, объект, значение), которые могут применяться к различным данным, более конкретными словами, которые будут правильными только для этого имени. Замените формулировку, которая имеет несколько возможных интерпретаций или значений (установить, запустить, проверить, вызвать, разместить, очистить, прервать - см. Https://muse.dillfrog.com/lists/ambiguous для дополнительных примеров) формулировкой, которая имеет меньше возможных интерпретации или значения.
Используйте большой словарный запас. Предпочитайте более богатое отдельное слово нескольким словам, если оно соответствует концепции. Тезаурус - ваш друг; просто поищите в Интернете свою концепцию, добавив в поиск «синонимы», и вы часто сможете найти слово или слова, которые более кратко и / или более точно описывают концепцию. Рефакторинг: замените несколько слов, описывающих концепцию, когда «для этого есть слово» (Employee вместо CompanyPerson).
Используйте термины проблемной области. Последовательно используйте и применяйте правильную терминологию, которую профильные эксперты используют в проблемной области. Это помогает решить проблемы связи, когда функции и требования (детали программирования) необходимо обсудить с отраслевыми экспертами. Рефакторинг: переименуйте идентификаторы, чтобы использовать правильную терминологию в проблемной области.
Составляйте имена, которые нельзя путать с другими именами. Избегайте использования имен, которые отличаются от существующих имен только по написанию (с тем же фонетическим произношением при разговоре) или только по формулировке (с тем же значением) , или только несколькими буквами, или только порядком слов. Используйте подходящие отличительные слова и не используйте имена, которые имеют одно и то же значение. Здесь цель состоит в том, чтобы предотвратить неправильное понимание того, что отличает каждый идентификатор, и не путать один с другим. Рефакторинг: сделайте различия более явными, добавляя, изменяя или используя разные слова. Каждый идентификатор должен легко отличаться от всех других идентификаторов.

Рекомендации по именам классов и методов:

Назовите классы, которые следует читать как существительную фразу, а методы - как глагольную фразу. Имя класса должно представлять сущность или классификацию - существительное (а не действие). Имя метода должно представлять действие или действие - глагол (а не объект). Функция, которая выполняет действие для возврата результата, должна иметь имя, которое представляет выполнение действия и обычно также указывает, чего ожидать от результата. Рефакторинг: переименуйте классы для представления существительного (IndividualTestResult вместо TakeATest) и переименуйте методы и функции для представления глагола (CalculateTestResult вместо TestResult).
Назовите классы так, чтобы они включали все возможные состояния и значения, которые класс может представлять. Если класс может существовать в нескольких состояниях или содержать множество значений, назовите класс так, чтобы он включал все эти состояния и разновидности. Рефакторинг: сделайте имя класса менее конкретным, чтобы учесть все возможные состояния и разновидности для этого класса (CargoVehicle вместо Truck, если класс представляет любое транспортное средство, которое может перевозить груз).
Будьте преднамеренными и прозрачными с использованием префиксов (get / set / is / has), слов проверки (validate / check / sure) и слов преобразования (transform / convert / as / to) в именах методов. В большинство этих слов заложены внутренние ожидания. Ожидается, что «get» прочитает / получит значение без каких-либо побочных эффектов. Ожидается, что «set» сохранит / перезапишет значение без каких-либо побочных эффектов. Ожидается, что «is» и «has» будут читать / извлекать логическое значение без каких-либо побочных эффектов. Ожидается, что «проверить», «проверить» и «гарантировать» будут возвращены результаты этой проверки, включая некоторые результирующие признаки отказа. «Transform» и «convert» и часто «to» и «as» в именах методов обычно ожидают выполнения некоторого преобразования на входе и возврата преобразованного объекта в качестве вывода. Рефакторинг: если какая-либо формулировка дает ожидание, которое не выполняется, либо измените метод / функцию, чтобы оно соответствовало ожиданиям, либо измените имя, чтобы оно не подразумевало это ожидание. Это включает формулировку, которая заставляет читателя ожидать отсутствия побочных эффектов; если есть побочные эффекты, переименуйте метод / функцию, чтобы лучше представить все, что они делают (или преобразовать их в несколько функций, каждая из которых имеет одну цель).

Любое нечеткое, двусмысленное, неточное, сокращенное, вводящее в заблуждение или непонятное название, используемое в нашей профессии, сопряжено с будущими издержками (дополнительные усилия, разочарование, путаница, ошибки и т. Д.). Частота использования плохих имен является важным фактором - чем они более распространены, тем более запутанным становится код в целом. Продолжительность жизни плохих имен является важным фактором - чем длиннее плохие имена остаются неизменными, тем больше накладных расходов они несут, поэтому, когда вы улучшаете имя, потратив время на выяснение его истинного назначения и более подходящего имени, это означает, что Будущим программистам, читающим его, не нужно тратить дополнительное время. Конечно, при переименовании обычно возникает компромисс (усилия, потраченные сейчас, и усилия, сохраненные позже), и переименование некоторых вещей требует больше усилий, чем переименование других, но во многих случаях дополнительные несколько секунд или минут, необходимые для переименования объекта, в конечном итоге оказываются равными. стоит того, чтобы сэкономить время и предотвратить проблемы для будущих программистов. И, наконец, согласованность между именами является большим фактором - множественность, синтаксис именования для классов / свойств / функций / и т. Д. В пределах языка, аббревиатуры, акронимы и использование заглавных букв - все это области, в которых несоответствия или двусмысленность могут значительно затруднить или вызвать проблемы для будущих разработчиков, пытающихся чтобы найти или сослаться на определенные вещи или категории вещей. Многие языки имеют довольно стандартизированные соглашения, и, помимо этого, важно, чтобы ваша программная организация определяла (или ссылалась) стандарты кодирования, которым необходимо следовать для языков, которые они используют больше всего. Включите проверку кода в свой обычный процесс программирования, чтобы убедиться, что код соответствует стандартам кодирования организации, и для повышения качества кода, попросив второго человека попытаться понять, что код имеет большое значение для сокращения будущих проблем и технического долга.

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

- Написано Томми Эллиоттом, руководителем группы разработчиков программного обеспечения в AWH, который работал в индустрии разработки программного обеспечения с 2010 года. Томми имеет опыт проектирования и создания веб-сайтов, API-интерфейсов, структур данных и мобильных приложений в небольших группах разработчиков для различных отраслей. .