Сделать программирование имя

Copyright ©2017 Питер Хилтон и Фелиенн Херманс

Абстрактный

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

Этим командам не хватает последовательных стандартов.

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

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

Затем в этой статье представлен сводный набор рекомендаций по именованию. Которые профессиональные программисты могут применять к написанному ими коду.

Почему имя имеет значение

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

Исследования когнитивных процессов понимания языка и текста показывают. Что именно семантика. Присущая словам. Определяет процесс понимания [14]

Каприле и Тонелла [15 ] утверждают,что идентификаторы предоставляют важную информацию о программных сущностях. Поскольку они дают программисту первоначальное представление о роли этих сущностей в рамках всей программы.

Дейсенбок и Пизка [14] не только излагают свое мнение об именовании. Но и проводят измерения. Они обнаружили. Что в базе кода Eclipse, которая состоит примерно из 2 МЛоК, 33% токенов и 72% символов посвящены идентификаторам.

Известно, что лучшие имена идентификаторов коррелируют с улучшенным пониманием программы. Например, [17] отчеты об исследовании. Проведенном с более чем 100 программистами. Которые должны были описать функции и оценить свою уверенность в этом. Их результаты показывают. Что использование полных идентификаторов слов приводит к лучшему пониманию кода. Чем использование однобуквенных идентификаторов. Измеряемых как рейтингом описания. Так и уверенностью в понимании. Однако они также обнаружили. Что во многих случаях нет никакой разницы между словами и аббревиатурами. Интересно, что это исследование также показало. Что женщины понимают больше из аббревиатур. Чем мужчины.

Возможно, было обнаружено. Что именование имеет значение для качества исходного кода. Butler et al. [16] оценили качество идентификаторов в восьми крупных Java-проектах в соответствии с рядом рекомендаций по стилю именования. Они обнаружили. Что возникновение нарушений именования коррелирует с проблемами кода. О чем сообщает FindBugs. Инструмент статического анализа для Java. В частности. Ошибки в написании заглавных букв. Использование слов. Не входящих в словарь. И использование более четырех слов коррелировали с проблемами.

Разработчики согласны с тем. Что именование имеет значение. В этнографическом исследовании. Проведенном среди двенадцати профессиональных разработчиков и восемнадцати студентов третьего курса [18], исследователи обнаружили. Что как студенты. Так и профессиональные разработчики считают важным использование рекомендаций по именованию. Исследование также выявило замечательную разницу между профессионалами и студентами: профессиональные разработчики уделяют больше внимания названию идентификаторов. Чем комментариям к исходному коду. Может быть, это связано с тем. Что курсы информатики. Как правило. Подчеркивают важность комментариев. Но в значительной степени пренебрегают именованием?

Хотя разработчики согласны с тем. Что руководящие принципы важны. На практике мы заметили. Что разработка программного обеспечения обычно оказывается дороже и занимает больше времени. Чем кто-либо ожидает. Как пишет Бугаенко [9], разработка программного обеспечения-это Мы видим. Что затраты на непрерывную разработку программного обеспечения включают в себя затраты на отладку. Исправление и поддержание кода. Эти действия явно требуют от программистов чтения и понимания существующего кода. Как программисты. Мы можем понять код. Только если знаем. Что он означает.

Мысленный эксперимент далее показывает. Что мы полагаемся на именование. Чтобы понять. Что означает код. Представьте себе. Что вы пытаетесь прочитать код после того. Как кто-то заменил каждое имя идентификатора символом подчеркивания. За которым следует случайное число. Хотя идентификатор типа resultпередает относительно мало намерений. Имя типа _42объясняет еще меньше.

Цель указания именования

Выше мы установили. Что именование важно. Но и трудно. Как лихо пошутила Карлтон:

— В информатике есть только две трудные вещи: аннулирование кэша и присвоение имен вещам. — Фил Карлтон

Мы думаем, что некоторые программисты делают ошибку. Сосредотачиваясь слишком много на исполняемости кода. А не на ценности кода как вещи для чтения людьми. Забывая о другой известной цитате:

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

Хорошее имя помогает будущему читателю кода быстро понять. Что означает значение. Тем самым делая код более читаемым и простым для понимания.

Однако программисты не всегда стараются писать код. Чтобы его можно было поддерживать. И когда они это делают. Им обычно трудно это сделать. Сама идея Точно так же компьютерная наука не имеет четкого определения Эти связанные меры сводят ‘ремонтопригодность’ к ‘удобочитаемости’.

Читабельность требует хорошего именования. Потому что плохие имена скрывают намерение программиста. Мы сообщаем выше. Что именование влияет на способность программистов читать и понимать исходный код. К сожалению. Программисты изо всех сил пытаются писать читаемый код. Потому что они изо всех сил стараются избегать использования плохих имен. Рекомендации по именованию направлены на то. Чтобы помочь программистам определить и избежать плохих имен. А также направить программистов к хорошим именам.

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

Существующие руководящие принципы

По нашему опыту. Профессиональные разработчики программного обеспечения не используют явные рекомендации по именованию широко. Несколько письменных стандартов кодирования. Широко используемых. Таких как [6], ограничивают свои рекомендации форматированием и длиной имени. Но предлагают мало. Чтобы прояснить разницу между хорошими и плохими именами.

Некоторые книги для разработчиков программного обеспечения включают раздел по именованию. Код Complete [4] включает в себя 30-страничную главу о силе имен данных. Это включает в себя четырнадцать рекомендаций по написанию лучших имен. Обсуждение различных соглашений об именовании. Список из одиннадцати запахов именования и контрольный список. Который обобщает эти рекомендации. Только для этой главы мы рекомендуем каждому профессиональному программисту иметь копию этой книги или. По крайней мере. Изучить собранные ниже рекомендации.

Clean Code [5] также содержит целую главу . Посвященную значимым именам, которая состоит из восемнадцати руководств. Большинство из этих рекомендаций непосредственно касаются самой сложной части именования: семантики. Более поздние книги по программированию. Как правило. Посвящают меньше слов именованию. Возможно, потому. Что им почти нечего добавить.

Исследования в области компьютерных наук иногда включают рекомендации по именованию. Работы Relf [2] и Arnaodova et al. [3] включают в себя сборники рекомендаций по именованию. Которые они оценивают по-разному. Ученые-компьютерщики, скорее всего, продолжат публиковать статьи, содержащие рекомендации по именованию, но профессиональные программисты редко имеют доступ к опубликованным работам, что делает их менее полезными непосредственно в индустрии программного обеспечения, чем книги.

Важность различных рекомендаций для профессиональных программистов

Профессиональные разработчики программного обеспечения получают больше пользы от некоторых видов рекомендаций. Чем от других. Такие рекомендации. Как имена переменных. Должны быть короткими. Но значимыми [6], звучат разумно. Но предлагают мало практической помощи. Как при выборе имени при кодировании. Так и при оценке имени во время проверки кода.

Некоторые академические исследования. Такие как Бинкли [10], сравнивали относительную читабельность различных соглашений о форматировании. Таких как camel-case (заглавные слова) и snake-case (слова. Разделенные подчеркиванием). В принципе, разработчики языков программирования могли бы использовать это исследование при создании этих соглашений для разработки языков программирования с более продуктивным опытом разработчиков. Но профессиональные программисты мало используют их.

Кен Арнольд типизирует точку зрения. Что ответственность за использование такого рода исследований для выбора стиля кодирования лежит на разработчиках языка. А не на программистах. В своем эссе

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

Я хочу, чтобы владельцы языковых стандартов занялись этим вопросом. Я хочу, чтобы следующая версия этих языков требовала любого кода. Который использует новые функции. Чтобы соответствовать какому-то стилю. [11]

Он утверждает. Что программисты следуют соглашению о форматировании имен. Принятому сообществом языков программирования. И что эти программисты ничего не выиграют от такого рода исследований.

Для любого языка существует один или несколько общих стилей кодирования. […]

В настоящее время нет и никогда не будет стиля программирования. Польза от которого значительно выше. Чем от любого из распространенных стилей. [11]

Однако Бинкли [10] приходит к выводу. Что не все В любом случае. Это остается результатом для языковых дизайнеров. А не для профессиональных программистов.

К счастью, некоторые исследования непосредственно касались полезности различных руководящих принципов. Релф, например. Приходит к выводу, что:

Рекомендации по стилю именования идентификаторов. Которые оказались наиболее полезными для программистов, требовали. Чтобы имена идентификаторов состояли из двух-четырех слов естественного языка или принятых в проекте аббревиатур; не должны состоять только из абстрактных слов; не должны содержать множественного числа слов; и должны соответствовать соглашениям об именовании проектов. [8]

Профессиональные программисты могут применять руководящие принципы с большей готовностью. Чем они могут получить доступ к оригинальным научным исследованиям и прочитать их. Особенно если они четко сформулированы. Поэтому мы стремимся представить большую коллекцию рекомендаций по именованию из ряда источников в форме. Которая делает их доступными для профессиональных программистов.

Стили руководящих принципов

Люди, которые пишут рекомендации по именованию. Формулируют свои рекомендации по-разному. Некоторые авторы пишут предписывающие инструкции, например, используют имена. Раскрывающие намерение [5], в то время как некоторые формулируют их как запахи кода или проблемы с именованием. Например Бессмысленные имена [1].

Мы рассмотрели ряд письменных рекомендаций по именованию [1-7]. Что касается стилей руководства. То мы приходим к выводу. Что одно руководство по именованию обычно содержит одно или несколько из следующих.

  • Предписывающие инструкции
  • Название запаха имя
  • Исправление имени рефакторинга
  • Пример нарушения руководящих принципов
  • Пример имя. Которое следует за руководством
  • Объяснение того. Почему руководство имеет значение или как оно работает

Именование запахов-это Запах кода указывает. Где вы можете улучшить свой код. И часто указывает на какую-то более глубокую проблему. Специфический запах кода часто сопровождается соответствующим рефакторингом. Который устраняет этот специфический запах. Улучшая код. Именование запахов появляется во многих формах. Но все они имеют один и тот же рефакторинг: Переименование.

Излишне говорить. Что программистам легче понять и применить последовательно написанные рекомендации. Наряду с последовательностью. Многочисленные объяснения помогают программистам применять руководящие принципы в различных сценариях. Запахи именования помогают программистам выявлять нарушения при проверке кода. В то время как предписывающие инструкции легче выполнять при написании кода. Примеры служат для объяснения как запахов. Так и инструкций. Абстрактная природа которых может затруднить их понимание.

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

Рекомендации по синтаксису

Рекомендации по синтаксису касаются того. Как идентификаторы строятся из слов и форматируются. Эти рекомендации не касаются того. Какие слова используют имена. За исключением руководства по использованию слов в первую очередь.

Использование соглашений об именах

Директива. Следуйте условностям языка программирования для имен. Языки программирования обычно имеют некоторые соглашения о том. Как писать имена идентификаторов, или. По крайней мере. Их спецификации или сообщества. Java-программисты, например. Следуют оригинальным рекомендациям Sun Microsystems [6] по использованию верхнего и нижнего регистра. Существительных и глаголов в именах классов. Интерфейсов, методов. Переменных и констант.

Рефакторинг. Применяйте стандартный случай со строгой последовательностью и используйте специальные инструменты проверки кода для его применения.

Пример нарушения. appleCOUNT, apple_count(когда верблюжий случай является стандартным).

Литература: [2], [6]

Замена числовых суффиксов

Директива. Не добавляйте номера к нескольким идентификаторам с одинаковым базовым именем. Если у вас уже есть employeeпеременная. То имя like employee2имеет столь же мало значения. Как another_employeeи .

Рефакторинг. Замените числа дополнительными словами. Описывающими разницу между несколькими идентификаторами. Которые в противном случае могли бы иметь одно и то же имя.

Пример нарушения. employee2

Ссылки: [1], [2], [4]

Используйте словарные слова

Директива. Используйте только правильно написанные словарные слова и аббревиатуры. Которые появляются в словаре. Делайте исключения idи документируйте доменные языки/аббревиатуры. Орфографические ошибки могут сделать имена неоднозначными и привести к запутанной непоследовательности. Аббревиатуры вводят другой вид двусмысленности. Которую исходный программист не видит. Потому что он знает. Какое слово означает аббревиатура. Даже если несколько слов имеют одну и ту же аббревиатуру.

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

Пример нарушения. acc, pos, char, mod, auth, appCnt

Список литературы: [1], [4], [5]

Разверните однобуквенные имена

Директива. Не делайте исключений из использования словарных слов для однобуквенных имен; используйте имена с возможностью поиска. Однобуквенные названия. Используемые в качестве аббревиатур. Вносят максимально возможную двусмысленность. В конечном итоге они используются с определенными значениями. Обычно по неписаному соглашению. Что затрудняет чтение кода программистами. Когда они впервые сталкиваются с этим соглашением или которым приходится переключаться между конфликтующими соглашениями в разных контекстах.

Одно исследование. Проведенное более чем 100 программистами. Которые сравнивали понимание отдельных букв,

Результаты показывают. Что полнословные идентификаторы приводят к лучшему пониманию; однако во многих случаях нет статистической разницы между использованием полных слов и аббревиатур. [12]

Рефакторинг. Используйте словарные слова.

Пример нарушения. i, j, k, l, m, n, t, x, y, z

Ссылки: [1], [2], [4], [5]

Артикулируйте символические имена

Директива. Не используйте художественные символы ASCII вместо слов в языках программирования. Которые его поддерживают. Делайте очень ограниченные исключения для документированных специфичных для предметной области символов, например+, в арифметике. По иронии судьбы. Программисты. Которые сталкиваются с символическими именами в сторонних библиотеках. Могут придумывать свои собственные имена. Но выбирают имена. Основанные на том. Как выглядит символ. А не на том. Что он означает.

Рефакторинг. Используйте словарные слова.

Пример нарушения. >=>, — допустимые идентификаторы функций в Scala, например. Разговорные названия fish и space ship.

Список литературы: [1]

Назовите постоянные значения

Директива. Назовите то. Что представляет собой константа. А не ее постоянное значение. Не стройте числовые имена констант из имен чисел.

Рефакторинг. Извлечение константы. Для запаха кода магического числа. Замените имена чисел либо доменными именами. Такими как pi, либо именем. Описывающим концепцию. Которую представляет число. Например boiling_point.

Пример нарушения. 3.142591, ONE_HUNDRED

Список литературы: [2], [4]

Используйте только одно подчеркивание за раз

Директива. Не используйте более одного последовательного подчеркивания. Несколько подчеркиваний обычно появляются в виде одной строки. Что затрудняет их подсчет.

Рефакторинг. Заменить одним подчеркиванием. Используйте инструменты. Предупреждающие. Когда имена содержат несколько символов подчеркивания.

Примеры нарушений. APPLE__COUNT

Список литературы: [2]

Используйте только подчеркивания между словами

Директива. Не используйте подчеркивания в качестве префиксов или суффиксов. Подчеркивания не имеют визуальной заметности. Что делает их хорошими разделителями слов. Но их легко неправильно прочитать до или после слова.

Рефакторинг. Обрезать подчеркивания. Используйте инструменты. Которые предупреждают. Когда имена не начинаются с буквы.

Пример нарушения. _APPLE_COUNT, APPLE_COUNT_

Список литературы: [2]

Ограничение длины символа имени

Директива. Держите длину имени в пределах максимум двадцати символов.

Результаты одного эксперимента с участием 158

[…] подкрепите прошлые предложения. Пропагандирующие использование ограниченной. Последовательной и регулярной лексики в именах идентификаторов. В частности. Хорошее именование ограничивает длину отдельных имен и уменьшает потребность в специальной лексике. [13]

Рефакторинг. Упростите имя. Извлеките переменную.

Примеры нарушений. ForeignDomesticAppleCount

Список литературы: [2]

Ограничьте количество слов имени

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

Рефакторинг. Упростите имя. Извлеките переменную.

Примеры нарушений. NewRedAppleSizeType, MyAppSizeType

Список литературы: [2], [4], [5], [8], [16]

Квалифицируйте значения с помощью суффиксов

Директива. Используйте суффикс. Чтобы описать. Какое значение представляют собой постоянные и переменные значения. Суффиксы типа minimumcountи averageсвязывают набор значений с одним производным значением. Использование в качестве определителя суффикса. А не префикса. Естественно. Связывает это имя с другими подобными именами.

Рефакторинг. Перенесите квалификацию в конец.

Примеры нарушений. MINIMUM_APPLE_COUNT (заменить на APPLE_COUNT_MINIMUM).

Список литературы: [2], [4]

Сделайте имена уникальными

Директива. Не перезаписывайте имя дубликатом в той же области. В Java, например. Локальная переменная Примите соглашение. Которое предотвращает двусмысленность в том. На какое имя программист намеревался ссылаться.

Рефакторинг. Добавление слов к одному из названий проясняет разницу между контекстами.

Список литературы: [2]

Руководство по лексике

Словарные рекомендации касаются выбора слов с обоснованием того. Что использование правильного слова имеет значение.

Опишите смысл

Директива. Используйте описательное имя. Значение которого описывает узнаваемое понятие с достаточным контекстом. Избегайте имен-заполнителей. Которые намеренно означают не что a_variableиное, как .

Рефакторинг. Опишите, что представляет собой идентификатор.

Примеры нарушений. foo, blah, flag, temp

Список литературы: [1], [4], [5]

Будьте точны

Директива. Определите конкретный вид информации и ее назначение. Неточные слова могут быть одинаково применимы к множеству идентификаторов и. Следовательно. Не различать их.

Рефакторинг. Замените неопределенные слова более конкретными словами. Которые были бы правильны только для этого имени.

Примеры нарушений. data, object

Список литературы: [1]

Выберите конкретные слова

Директива. Используйте слова. Которые имеют одно ясное значение. Как и неточные слова. Абстрактные слова могут одинаково применяться к нескольким идентификаторам.

Рефакторинг. Замените более конкретными словами. Которые сужают понятие. К которому они относятся.

Пример нарушения. Manager суффикс, getпрефикс, doIt

Список литературы: [1], [2]

Используйте стандартный язык

Директива. Избегайте быть милым или смешным. Когда это приводит к названию. Которое требует общей культуры или больших усилий для понимания. Как и намеренно бессмысленные имена. Милые и смешные имена требуют от читателя понимания некоторого неявного контекста. В то время как юмор часто опирается на косвенные ссылки и двусмысленность. Эти качества не улучшают читаемость кода.

Рефакторинг. Замените косвенные ссылки и разговорный язык соответствующим эксплицитным и стандартным языком.

Пример нарушения. whack вместо того. Чтобы убивать.

Список литературы: [5]

Используйте большой словарный запас

Директива. Используйте более богатое одно слово вместо нескольких слов. Описывающих хорошо известное понятие. Используйте слово. Которое наиболее точно относится к понятию. На которое ссылается идентификатор.

Рефакторинг. Замените несколько слов. Описывающих концепцию, когда

Пример нарушения. CompanyPerson (заменить на Employee).

Список литературы: [1]

Используйте термины проблемной области

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

Рефакторинг. Переименуйте идентификаторы. Чтобы использовать правильную терминологию.

Пример нарушения. Order когда вы имеете в виду Shipment, в контексте цепочки поставок. Где это означает что-то другое.

Список литературы: [1], [4], [5]

Заставьте имена отличаться более чем на одну или две буквы

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

Рефакторинг. Сделайте разницу более явной. Добавив или изменив слова.

Примеры нарушений. appleCount против appleCounts

Ссылки: [2], [4], [5]

Сделать имена отличаются более чем порядком слов

Директива. Не используйте имя. Которое отличается только от существующего имени в порядке слов. Не используйте два имени. Которые объединяют один и тот же набор слов.

Рефакторинг. Сделайте разницу более явной. Используя разные слова. А не просто другой порядок слов для передачи разных значений.

Пример нарушения. appleCount против countApple

Список литературы: [2]

Сделать имена разными по смыслу

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

Рефакторинг. Переименуйте обе переменные с более явными именами.

Пример нарушения. input/inputValue, recordCount/numberOfRecords

Список литературы: [4]

Сделать имена различаются фонетически

Директива. Не используйте имена. Которые звучат одинаково. Когда говорят. Цель-написать код. Который другой программист мог бы записать правильно. Если бы вы прочитали его вслух. Хотя они не транскрибируют код таким образом. Как правило. Они часто говорят о коде.

Рефакторинг. Замените омофон синонимом.

Пример нарушения. wrap/rap

Список литературы: [4]

Рекомендации по типу данных

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

Опустить информацию о типе

Директива. Не используйте префиксы или суффиксы. Которые кодируют тип данных. Избегайте венгерской нотации и ее остатков. Не ставьте перед логическими типизированными значениями и функциями префикс is.

Рефакторинг. Удалите слова. Которые дублируют тип данных. Буквально или косвенно.

Пример нарушения. isValid, dateCreated, iAppleCount(заменить на valid, created, appleCount).

Ссылки: [1], [2], [5]

Используйте имена в единственном числе для значений

Директива. Не используйте множественное число имен для отдельных значений.

Рефакторинг. Замените множественное число формой единственного числа.

Пример нарушения. appleCounts (заменить на appleCount).

Список литературы: [2], [3]

Используйте имена коллекций во множественном числе

Директива. Множественное число имен для значений коллекций. Таких как списки. Технически это противоречит рекомендации избегать кодирования информации типа в именах. Но английская грамматика требует. Чтобы она позволяла читать код нормально или вслух.

Рефакторинг. Используйте форму множественного числа.

Пример нарушения. remainingApple для набора яблок (заменить на remainingApples).

Список литературы: [3]

Предпочитаю собирательные существительные для коллекций

Директива. Если тип коллекции имеет собирательное существительное. В контексте имени используйте его вместо множественного числа.

Рефакторинг. Используйте собирательное существительное. Когда это возможно. Вместо обычной формы множественного числа.

Пример нарушения. appointments (заменить на calendar), pickedApples(заменить на harvest).

Список литературы: [1]

Используйте противоположности точно

Директива. Последовательно используйте противоположности в стандартных парах с соглашениями об именовании. Типичные пары включают add/remove, begin/end, create/destroy, destination/source, first/last, get/release, increment/decrement, insert/delete, lock/unlock, minimum/maximum, next/previous, old/new, old/new, open/close. Put/get, show/hide. Source/destination. Start/stop. Target/source и up/down.

Рефакторинг. Используйте правильную противоположность и используйте ее последовательно.

Пример нарушения. first/end

Список литературы: [4]

Используйте логические имена переменных подразумевающие true или false

Директива. Используйте имена типа doneилиfound, описывающие логические значения. Используйте обычные логические имена, возможно. Из списка условных обозначений кода.

Рефакторинг. Замените логические имена именами в правильной грамматической форме.

Пример нарушения. status например started

Список литературы: [4]

Используйте положительные логические имена

Директива. Не используйте отрицание в логических именах. Не используйте имена. Которые требуют такого префикса, notкоторый инвертирует значение истинности переменной.

Рефакторинг. Инвертируйте значение и удалите префикс.

Пример нарушения. notSuccessful

Список литературы: [4]

Рекомендации по названию класса

Рекомендации по именам классов специально адресуют имена классов в объектно-ориентированных языках программирования.

Используйте имя существительного-фразы

Директива. Назовите класс существительной фразой. Чтобы вы могли использовать имя класса для завершения фразы Конструктор этого класса возвращает новый…. Следуйте грамматическим правилам объектно-ориентированного программирования.

Рефакторинг. Добавьте отсутствующее существительное. Не забывая выбирать конкретные слова.

Пример нарушения. Calculate (заменитеDiscountRule, например, на).

Литература: [5], [6]

Используйте имя. Которое допускает все возможные состояния

Директива. Не используйте имена классов. Которые предполагают определенное состояние. Если класс моделирует что-то. Что может иметь несколько состояний. То избегайте имени. Которое было бы несовместимо с состоянием. Которое является результатом вызова метода. Который изменяет это состояние.

Рефакторинг. Сделайте имя класса менее специфичным для размещения всех возможных состояний.

Пример нарушения. disableМетод. Который возвращает ControlEnableState(переименовать класс в ControlState).

Список литературы: [3]

Выберите имя, соответствующее возможным значениям

Директива. Не используйте имя. Которое кажется противоречащим определенным возможным значениям. Некоторые типы агрегируют несколько значений одного и того же типа. Например , строка. Которая имеет a startи an end, поэтому используйте имя. Которое одинаково применяется к обоим значениям. НапримерExtremity, вместо того. Чтобы называть тип только после одного возможного значения. Например Start.

Рефакторинг. Сделайте имя класса включительным.

Пример нарушения. start поле имеет тип MAssociationEnd(переименовать класс в MAssociationExtremity).

Список литературы: [3]

Рекомендации по названию метода

Рекомендации по именам методов специально обращаются к именам методов в объектно-ориентированных языках программирования. Некоторые из этих рекомендаций применимы к Java. В частности. Из-за вредных привычек. Поощряемых спецификацией JavaBeans [6].

Используйте имя глагола-фразы

Директива. Сделайте имя метода активной глагольной фразой. За исключением методов доступа. Как и в случае с руководством по использованию именных фраз для названия класса. Следуйте грамматическим соглашениям объектно-ориентированного программирования. Некоторые стили кодирования опускают глагол из методов доступа. Меняя Parcel.getWeight()его на Parcel.weight(). Другой распространенный стиль-опустить глагол из методов преобразования. Изменив Discount.convertToPercentage()на Discount.asPercentage().

Рефакторинг. Добавьте отсутствующий глагол. Не забывая выбирать конкретные слова.

Пример нарушения. calculation()

Литература: [5], [6]

Не используйте getisпрефиксы или hasпрефиксы для методов с побочными эффектами

Директива. Используйте глагольную фразу. Которая предполагает побочный эффект. Если он есть. Глаголы вроде createи convertпредполагают побочный эффект. В то время как другие предполагают идемпотенцию.

Рефакторинг. Замените

Пример нарушения. getImageData метод. Который создает новый объект.

Список литературы: [3]

Использовать только get, isи hasпрефиксы для методов. Которые только выполняют доступ к полю

Директива. Используйте префиксы имен обычных методов доступа только для методов доступа. Которые непосредственно возвращают значение поля. В Java спецификация JavaBeans [7] требует этих префиксов для определенных методов. Когда некоторые методы требуют определенного префикса. Не используйте те же префиксы для методов. Которые их не требуют.

Рефакторинг. Замените

Примеры нарушений. getScore который выполняет вычисления или обращается к внешним данным.

Используйте getпрефикс только для методов доступа к полю возвращающих значение

Директива. Не используйте getпрефикс имени метода доступа к полю для методов. Которые не возвращают значение.

Рефакторинг. Замените

Примеры нарушений. getMethodBodies заполняет тела методов. Но не возвращает их.

Список литературы: [3]

Используйте только ishasпрефиксы и для методов доступа к логическим полям

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

Рефакторинг. Замените префикс getна префикс или удалите его полностью.

Пример нарушения. isValid возвращает intзначение.

Список литературы: [3]

Используйте setпрефикс только для методов доступа к полю, которые не возвращают значение

Директива. Не используйте setпрефикс имени метода доступа к полю для методов. Возвращающих значение.

Рефакторинг. Замените

Пример нарушения. setBreadth создает и возвращает новый объект или обновляет и возвращает this(fluent API).

Список литературы: [3]

Используйте только глаголы проверки для методов. Которые обеспечивают результат

Директива. Используйте только глаголы типа validatecheckили ensureдля именования методов . Которые либо приводят к возникновению исключения. Либо вызывают его при неудачной проверке.

Рефакторинг. Возвращаемый результат.

Примеры нарушений. validateSnaps и checkCurrentStateэто возвращение void.

Список литературы: [3]

Используйте только глаголы преобразования для методов. Возвращающих преобразованное значение

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

Рефакторинг. Верните результат или измените глагол. Чтобы указать. Что преобразует метод.

Примеры нарушений. javaToNative с типом возврата void.

Список литературы: [3]

Отклоненные рекомендации

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

Использование длинных имен для длинных областей

Когда вы даете переменной короткое имя , напримерi, сама длина говорит что — то о переменной, а именно. Что переменная является пустым значением с ограниченной областью действия. [4]

Длина имени должна быть связана с длиной области действия. Вы можете использовать очень короткие имена переменных для крошечных областей. Но для больших областей вы должны использовать более длинные имена. [5]

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

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

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

Краткое Имя идентификатора

[избегайте] имени идентификатора короче восьми символов. Исключая:i,j, k,l, m,n,tx, yили z[2]

Имена переменных должны быть короткими. Но значимыми. Выбор имени переменной должен быть мнемоническим — то есть предназначенным для указания случайному наблюдателю на намерение ее использования. Следует избегать односимвольных имен переменных. За исключением временных Общими именами временных переменных являются i, j, k, m, и nдля целых чисел; c, d, и eдля символов. [6]

Мы не используем это руководство на практике. Потому что больше заботимся о том. Чтобы избежать аббревиатур (см. На самом деле мы отчасти согласились бы с этими рекомендациями. Если бы не их исключения для однобуквенных имен. Которые мы считаем худшим видом аббревиатуры.

Длинное Имя идентификатора

[избегайте] имени идентификатора длиной более двадцати символов [2]

Мы лишь отчасти принимаем это правило. Потому что предпочитаем. Чтобы имена были настолько длинными. Насколько это необходимо. Однако мы также считаем имя длиной более двадцати символов подозрительно длинным и ищем либо более простое имя. Либо извлекаем промежуточное объявление. Что иногда упрощает дело с длинным именем.

Количество слов

идентификатор должен состоять из двух. Трех или четырех слов [2]

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

Квалификация класса/Типа

имена классов и типов должны быть квалифицированы для определения их природы [ … ]. Например Fruit(FruitClass и Fruit_Treeсчитаются более читаемыми) [2]

Мы отвергаем это руководство. Как и участники исследования (в [2]. Мы бы рассмотрели добавление Classсуффикса имени класса как избыточное. Многие языки используют соглашение о капитализации для имен типов и classключевое слово для объявлений. Кроме того, профессиональные разработчики программного обеспечения. Как правило. Используют инструменты (IDE). Которые указывают. Какие идентификаторы являются типами. Или поддерживают навигацию к объявлению. Мы никогда не слышали. Чтобы кто-то систематически принимал это руководство.

Постоянная/Переменная Квалификация

числовые константы диапазона должны быть полностью квалифицированы […] например Minimum_Apple_Count(Apple_Count_Minimum считается более читаемым) [2]

Это руководство кажется разумным. Но мы, вероятно. Иногда предпочитаем грамматический порядок английских слов.

Единственное слово

имена идентификаторов должны состоять из слов в единственном числе [2]

Мы отвергаем это руководство. Потому что оно не учитывает типы коллекций. Но его легко исправить. Используйте только имена в единственном числе для отдельных значений и только имена во множественном числе для коллекций.

Похожие Имена Идентификаторов

[избегайте] появления двух одинаковых имен идентификаторов как в области действия [2]

Мы не знаем. Следует ли принимать это руководство. Потому что на практике мы не испытываем этой проблемы и не знаем. Насколько обременительной она нам покажется.

Порядок определения Идентификатора перечисления

[избегайте] перечисления констант. Объявленных в не алфавитном порядке [2]

Мы частично принимаем это руководство, которое. По крайней мере. Требует порядка и. Таким образом. Предотвращает (по-видимому) случайный порядок. Однако некоторые перечисления. Такие как дни недели. Имеют свой собственный не алфавитный естественный порядок. К счастью, мы не следуем слепым указаниям.

Квалификация идентификатора перечисления

[избегайте] неквалификации констант перечисления для идентификации их базового типа [2]

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

Дальнейшие исследования

Хотя разработчики согласны с тем. Что руководящие принципы важны [18]. Они остаются недостаточно используемыми в индустрии программного обеспечения. По нашему опыту. Профессиональные разработчики программного обеспечения не всегда согласны с тем. Какие рекомендации использовать. Или даже с тем. Что они стоят. Для дальнейшего совершенствования практики именования наша отрасль выиграла бы от более строгих ответов на следующие вопросы.

  1. Какие принципы именования универсально применимы ко всем видам кода?
  2. Какие рекомендации по именованию оказывают наиболее положительное влияние на читаемость и ремонтопригодность кода?
  3. Можем ли мы с пользой свести рекомендации по именованию к короткому контрольному списку для использования в обзоре кода?
  4. Может ли майнинг больших коллекций генерировать стандартные словари
  5. Как разработчики программного обеспечения должны писать рекомендации по именованию?
  6. Как разработчики программного обеспечения должны использовать рекомендации по именованию?
  7. Можно ли измерить качество имени идентификатора или эффективность руководства по именованию?
  8. Что мы можем узнать из анализа затрат и выгод. Связанных с рекомендациями по именованию?
  9. Как соотносятся рекомендации по именованию и именованию с документацией по программному обеспечению?
  10. Уменьшает ли улучшение именования потребность в комментариях кода?
  11. Значительно ли парное программирование и программирование мобов улучшают качество именования?
  12. Как английский словарь и тезаурус могут помочь программистам выбрать эффективные имена?
  13. Какие методы положительно влияют на совершенствование навыков именования программистов?
  14. Какие инструменты поддержки именования еще не протестированы программистами в промышленных условиях?
  15. Как родной язык программиста влияет на их подход к выбору английских идентификаторов?

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

Рекомендации

  1. Питер Хилтон — Именование запахов (2016)
  2. Phillip Relf — Достижение качества программного обеспечения за счет удобочитаемости исходного кода (2004)
  3. Венера Арнаудова. Массимилиано Ди Пента и Джулиано Антониоль — Лингвистические Антипаттерны: что они собой представляют и как их воспринимают разработчики (2015)
  4. Стив Макконнелл — Code Complete, Microsoft Press (1993)
  5. Роберт К. Мартин — Чистый код, Прентис Холл (2009)
  6. Sun Microsystems — Соглашения о коде для языка программирования Java TM (20 апреля 1999)
  7. Sun Microsystems — JavaBeans — Спецификация API JavaBeans™ версии 1.01 (1997)
  8. Phillip Relf — Улучшение Читаемости Исходного Кода С Использованием Эвристических Динамических Отчетов Об Ошибках При Редактировании— докторская диссертация (2007)
  9. Егор Бугаенко — Сколько Стоит Это Программное Обеспечение?
  10. Дэйв Бинкли. Марсия Дэвис. Дон Лори и Кристофер Моррелл — В camelCase или Под score (2009)
  11. Ken Arnold — The Best Software Writing I (2005, ed. Joel Spolsky), pp 1-6, ранее опубликованный в Интернете как Style is Substance (2004)
  12. Дон Лори, Кристофер Моррелл. Генри Фейлд и Дэвид Бинкли — Эффективные имена идентификаторов для понимания и памяти (2007)
  13. Дэйв Бинкли, Дон Лори. Стив Мейкс и Кристофер Моррелл — Длина идентификатора и ограниченная память программиста (2009)
  14. F. Deißenböck and M. Pizka — Краткое и последовательное именование (2005) В Трудах IWPC 2005.
  15. B. Caprile and P. Tonella — Restructuring program identifier names (2000) In Proceedings of ICSM, 2000.
  16. Саймон Батлер. Мишель Вермелингер. Ицзюнь Юй и Хелен Шарп — Соотнесение Недостатков именования идентификаторов и качества кода: Эмпирическое исследование (2009) В Proceedings of WCRE 2009.
  17. Дон Лори, Кристофер Моррелл. Генри Фейлд и Дэвид Бинкли — Что это за Имя? A Study of Identifiers (2006) In Proceedings of ICPC 2006.
  18. Феличе Сальвиуло и Джузеппе Сканьелло — Работа с идентификаторами и комментариями в понимании и обслуживании исходного кода: результаты этнографически обоснованного исследования со студентами и профессионалами (2014) В Proceedings of EASE 2014