Насколько «самодокументированным» может быть код, не раздражая его?

Asked
Viewd2308

35

Я не уверен, какие здесь передовые методы, но я часто вижу сокращенные имена переменных, особенно когда область действия мала. Итак (используя простые примеры Ruby) вместо def add_location(name, coordinates), я вижу такие вещи, как def add_loc(name, coord) - и я могу даже видеть что-то вроде def add_loc(n, x, y). Я полагаю, что более длинные имена могут утомить человека, когда он привык видеть аббревиатуры.

Многословие способствует удобочитаемости или просто у всех режет глаза? - Люди предпочитают сокращения и сокращенные имена длинным именам?

20 ответов

55

Лично я НАМНОГО предпочел бы видеть более длинные имена, которые на самом деле что-то значат, без необходимости сначала определять контекст. Конечно, переменные, которые не придают реального значения, такие как счетчики, я все еще использую небольшие бессмысленные имена переменных (например, i или x), но в остальном подробность - это ясность большую часть времени. Особенно это касается общедоступных API.

Однако можно зайти слишком далеко. Я видел в прошлом какой-то код на VB, такой нелепый. Модерация, как и все остальное!

  • Точно, вы пишете код только один раз, но вы прочитаете его тысячу раз, поэтому сделайте код удобным для чтения.

    Tom Pažourek20 февраля 2010, 13:36
14

На самом деле я постоянно использую длинные имена переменных, после того как все современные IDE и текстовые редакторы имеют завершение, поэтому нет ничего плохого в использовании index вместо этого, если i. Единственное исключение, которое у меня есть, это когда я имею дело с координатами b / c x и y, которые имеют наибольший смысл там.

  • for (index = 0; index <9; index ++), как неприятно читать. Более длинное название в этом случае не помогает.

    Jules04 января 2009, 22:50
  • Любой хороший текстовый редактор (я использую (g) vim) тоже может это сделать, поэтому я не понимаю вашей точки зрения.

    André17 октября 2008, 23:42
  • Я думаю, что полагаться на вашу IDE для поддержки кода, который в противном случае был бы громоздким, в целом, плохая идея.

    Lucas Oman17 октября 2008, 23:31
0

«Разгадывать тайны убийства - это нормально, но вам не нужно разгадывать код. Вы должны уметь его читать». - Стив К. МакКоннелл

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

6

Я просмотрел ответы, но не вижу, охвачено ли следующее. Вот оно ...

Сокращаете ли вы слово или говорите многословно, просто убедитесь, что вы использовали не больше слов, чем необходимо, а значение чертовски очевидно.

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

 def initialize_report_template()
end
 

должно было быть ...

 class ReportTemplate
    def initialize()
    end
end
 
1

Я согласен с Килхоффером; Я предпочитаю видеть описательные имена переменных почти в каждом контексте. Я буду сокращать, если имена моих переменных длиннее 20 символов или около того, обычно со словами в имени переменной (например: "SomeVeryLongVarValue").

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

  • Знаете, я начинал в мире VB5 / 6, где нотация в венгерском стиле была "входной" вещью ... Мне это никогда не нравилось, но это только я лично.

    Matthew Scharley17 октября 2008, 23:53
  • Раньше я использовал его во времена VB6, но прекратил после появления .NET (гильдии VB.NET отказались от него)

    Booji Boy18 октября 2008, 00:25
  • Венгерская нотация мне кажется странной.

    keyofnight18 октября 2008, 00:21
3

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

Пример 1. Аргумент метода, тип которого уже передает всю необходимую информацию.

Пример 2: переменная, которая будет широко использоваться очевидным образом

 StringBuilder sb = ...
sb.append(...
sb.append(...
return sb.toString();
 

Пример 3. Идиоматические сокращения. i, j, k уже упоминалось. "sb" выше - один в нашем коде, и у каждой команды, вероятно, есть еще пара.

  • sb - довольно распространенное сокращение для local StringBuilder, но я бы использовал что-то более интуитивное, если бы оно использовалось вне текущей функции.

    Matthew Scharley18 октября 2008, 00:51
  • Понятно. Хотя я мог представить, что напишу database = Sequel.new(...), я бы не возражал против общего примера DB = Sequel.new(...)

    keyofnight18 октября 2008, 00:18
0

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

Чем больше подробностей, тем обычно лучше. В хорошей среде разработки у вас все равно должно быть завершение кода, поэтому вы можете просто нажать «add_L» + TAB, чтобы завершить вызов метода.

0

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

Я мог бы принять add_loc (имя, координаты), поскольку они достаточно длинные, я могу сказать, что это такое. В add_loc (n, x, y) я бы возразил против 'n' вместо имени. Я мог бы жить с X и Y, поскольку это общепринятые названия координат.

Для тех, кто не знаком с системами координат, я мог бы увидеть, где add_location (имя, координаты) было бы более значимым.

В случае сомнений используйте более длинные имена.

10

Попробуйте прочитать свой собственный код через год. Вы увидите как значение самодокументируемых имен переменных, так и значение комментариев к коду (и особенно значение чистого кода)

Когда вы берете чужой исходный код и не понимаете его, легко подумать: «Ну, он не такой хороший программист, как я». Но когда вы понимаете, что ваш собственный код трудно читать, вы думаете: « о чем я думал? "

В конечном итоге многословие способствует удобству обслуживания. Для короткого однострочного скрипта вы все равно можете использовать "setLocNm" вместо setLocationName "

Любой дурак может написать код, понятный компьютеру. Хорошие программисты пишут код, понятный людям. -Мартин Фаулер

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

    keyofnight18 октября 2008, 00:20
7

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

Вот мои общие правила:

  • Итератором может быть одна буква, т.е. i, j, k и т. Д.
  • Другие однословные переменные, такие как логические переключатели, которые у вас никогда не сокращаются, т.е. installing, done и т. Д.
  • Переменные, состоящие из нескольких слов, и имена функций могут быть сокращены, но только в том случае, если они начинают становиться чрезмерно длинными (скажем, 20-25 + символов). Ключевым моментом здесь является умная аббревиатура. Например, function => func, но никогда не fun, f или functi
  • Забавно, мне нравится веселье больше, чем func (возможно, потому, что OCaml использует веселье).

    Jules04 января 2009, 22:53
  • "Веселье" всегда кажется мне двусмысленным, потому что это отдельное слово.

    Matthew Scharley09 января 2009, 10:04
3

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

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

  • Поскольку контекст вопроса - Ruby, XCoordinateForCurrentLocationOfSelf в любом случае является константой…

    Mike Woodhouse17 октября 2008, 23:51
  • Я думаю, что XCoordinateForCurrentLocationOfSelf граничит с смешным, но не совсем смешным.

    Kilhoffer17 октября 2008, 23:25
  • selfCurrentX, childTargetX, relatedCacheX; пока вы последовательны , можно понять подразумеваемое значение из контекста (а быть последовательным также означает использовать self, child, связанный для ссылки на объекты, X которых используется / изменяется).

    eyelidlessness17 октября 2008, 23:41
  • В .NET это, вероятно, можно было бы сделать с помощью LocationOfSelf как Point или Rectangle, тогда вы могли бы указать это как LocationOfSelf.X или LocationOfSelf.Left. Абстракция побеждает.

    Matthew Scharley18 октября 2008, 00:49
  • Я полагаю, это зависит от контекста; Если такое длинное имя необходимо, чтобы отличить его от других двенадцати переменных с координатой x, я мог бы использовать это.

    Lucas Oman17 октября 2008, 23:32
  • Лукас… отличное замечание!

    Kilhoffer17 октября 2008, 23:33
3

Старайтесь быть короче, чем длиннее, но понимание читателя должно преобладать над лень печатать каждый раз.

Как уже говорили другие, длина имени переменной не должна скрывать логику или алгоритм. Например, в арифметике мы пишем

 ( 1 + 5 ) * 3 = 18
 

а не

 three multiplied by the sum of one and five equals eighteen
 

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

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

1

Меня, наверное, полностью освистят, но я хотел убедиться, что это мнение было услышано.

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

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

Удачи.

-2

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

0

Я думаю, что основная проблема с сокращениями заключается в том, что не все люди используют аббревиатуры одинаково , поэтому, когда вы работаете с большим количеством людей, это может только увеличить вероятность ошибки при кодировании. Например, если у вас есть константа, которую можно назвать SOMETHING_INTERFACE, возможно, некоторые разработчики сократят ее как SOMETHING_INTFACE, другие как SOMETHING_IFACE или SOMETHING_IF, SMTHING_IFACE ...

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

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

12

Никогда не сокр.

12

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

Излишняя многословность скрывает синтаксис, и синтаксис важен.

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

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

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

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

-1

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

1

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

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

  • Даже в этом случае короткое имя может быть плохой идеей ... возьмем, например, значение расстояния в "distance = getLightYears () * 0.30659458;" может не подходить, если вы не понимаете, что все последующие вычисления выполняются в парсеках, затем конвертируются в световые годы, а затем возвращаются…

    James Schek18 октября 2008, 00:15
  • Что ж, с точки зрения удобочитаемости, это ужасное магическое число, которое у вас есть, и его следует правильно назвать, чтобы указать, что оно имеет дело с парсеками. Я сказал, что это единственное место, где я его принимаю, а не то, что они должны использоваться там все время.

    William20 октября 2008, 22:05