Содержательные и краткие рекомендации по присвоению имен

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

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

Например, это может быть частью руководящих принципов, которые я наблюдаю:

• Используйте Добавить, когда существующий элемент будет добавлен к цели, Используйте Создать, когда новый элемент создается и добавляется к цели.
• Используйте Удалить, когда существующий элемент будет удален из цели, Используйте Удалить, когда элемент будет удален навсегда.
• Сопряжение методов AddXXX с методами RemoveXXX и Сопряжение методов CreateXXX с методами DeleteXXX, но не смешивайте их.

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

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

Нейминг. Одна из самых сложных вещей в разработке программного обеспечения :)

Когда я называю что-то, вот мой набор приоритетов:

• Следуй идиомам моего языка. Руби любит подчеркивания. Javascript нравится верблюжий чехол. На каком бы языке вы ни находились, это соглашение, которому нужно следовать.
• Раскрывает намерение API. Это не "send_http_data", это "post_twitter_status"
• Избегайте утечки деталей реализации. Скажем, префикс переменной с типом.
• Не использует больше символов, чем необходимо, не нарушая предыдущие рекомендации.

Очевидно, это довольно упрощенный подход. Наименование нюансов.

Для дальнейшего исследования я бы порекомендовал прочитать «Искусство читаемого кода» , так как он дает несколько отличных, кратких советов по именованию методов. Для еще большего исследования я не могу более рекомендовать Чистый код Боба Мартина

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

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

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

Для меня поиск хорошего имени для чего-то всегда возвращается к мысли о нем как об объекте, который должен оправдывать его существование. Спроси себя:

• Что делает класс / метод / переменная, то есть какова его более широкая цель и для чего она нужна?
• Что конкретно о его цели нужно сообщать, то есть, что является важной частью, что имя должно иметь в нем?

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

Код должен быть самодокументированнымто есть, ваше наименование должно показывать, что что-то делает. Если вам нужно объяснить, что строка кода делает в комментарии, и переименование вещей недостаточно улучшает ее, вам следует серьезно подумать о рефакторинге этой строки в новый метод с соответствующим описательным именем, чтобы чтение исходного метода, вызов нового метода описывает, что происходит. Не бойтесь иметь длинные имена; Конечно, вы не должны писать романы в именах классов / методов / переменных, но я бы предпочел, чтобы имя было слишком длинным и описательным, чем слишком коротким, и мне нужно выяснить, что оно делает, заглянув под капот. За исключением некоторых очевидных исключений, таких как координаты x / y и часто используемые аббревиатуры, избегайте односимвольных имен и сокращений. Вызов чего-то "bkBtn" вместо "backButton"

Столько, сколько позволяет ваш язык, сделайте так, чтобы ваш код читался как английское предложение. Объекты используют существительные, методы используют глаголы. Булевы методы обычно начинаются с «is», но есть много других опций, которые передают значение еще лучше, в зависимости от варианта использования, таких как «can», «should» или «делает». Конечно, не все языки могут быть настолько хороши, как Smalltalk, но некоторые символы обычно считаются частями предложения. Два соглашения Smalltalk, которые я лично хотел бы перенести на другие языки в максимально возможной степени, - это добавление префикса имени цикла к параметру «each» и добавление параметра метода к статье «a» (или «an», или «some» для коллекций). , Это может не быть распространенным стандартом в Java, и любой может проигнорировать этот бит, но я считаю, что это значительно улучшает читабельность кода. Например (пример на Java):

public boolean shouldConsiderAbbreviating(List<String> someNames) {
  for (String eachName : someNames) {
    if (isTooLong(eachName)) {
      return true;
    }
  }
  return false;
}

Это должно быть доступно для чтения людям с небольшим знанием Java как-то так:

Чтобы определить, стоит ли сокращать список некоторых имен (которые являются строками), перебирайте некоторые имена и для каждого имени определяйте, является ли он слишком длинным; если так, вернись true; если ни один не слишком длинный, вернитесь false.

Сравните приведенный выше код с простым именованием аргумента stringsи переменной цикла string, особенно в более сложном методе. Вы должны внимательно посмотреть, чтобы увидеть разницу, а не использование очевидным с первого взгляда на название.

Поиск хорошего наименования - это всегда компромисс между многими факторами. Вы никогда не будете полностью удовлетворены.

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

В общем, рассматривайте такие вещи, как object.method(parameters)соответствие схеме, например subject.verb(complements).

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

Что касается существительных, классы должны быть названы для того, что они are(с точки зрения концепции), а объекты для того, что они are for.

Тем не менее, между list.add(component)и component.add_to(list)предпочитаю первое. В целом, «активные переходные» глаголы лучше представляют действия относительно их пассивных или рефлексивных аналогов. Если дизайн не ограничивает вас.

Не беспокойтесь о длине имен методов. Убедитесь, что имена методов четко отражают то, что они делают. Это имеет первостепенное значение для всего остального. Если вы чувствуете, что имя метода слишком длинное, используйте тезаурус, чтобы найти более короткое слово, которое означает то же самое. Например используйте Findвместо Retrieve.

Также не менее важны имена, которые вы выбираете для своих занятий. Они предоставляют много контекста при взгляде на имена методов. Подпись метода выглядит так:

public User Find(int userId);

легче понять, чем:

public Person Find(int personId);

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

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

Некоторые платформы предпочитают короткие имена (например, в Win32 C API _tcsstrесть функция для нахождения строки в строке - разве это не очевидно?), Другие предпочитают удобочитаемость в пользу краткости (в каркасе Apple для Objective-C) вызывается метод замены подстроки в строке другой строкой и возврата результата при копировании stringByReplacingOccurrencesOfString: withString:). Я считаю, что последнее намного проще для понимания, и писать его довольно сложно (особенно с завершением кода).

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

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

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

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

1. Используйте префикс. Если для выполнения чего-то похожего используется куча методов или они могут быть каким-то образом сгруппированы, перед их именами ставьте общий префикс, чтобы показать, что общего у этих методов.
2. Не используйте неясные сокращения, если вы хотите, чтобы другие сразу поняли имена (важно для именования API)