Насколько "самодокументируемый" код может быть без раздражения?
Я не уверен, что здесь есть лучшие практики, но я часто вижу сокращенные имена переменных, особенно когда область мала. Так что (использовать простые примеры Ruby) вместо def add_location(name, coordinates)Я вижу такие вещи, как def add_loc(name, coord)- и я мог бы даже увидеть что-то вроде def add_loc(n, x, y), Я полагаю, что более длинные имена могут утомить человека, когда он привык видеть аббревиатуры.
Помогает ли многословие читабельности, или это просто ранит глаза у всех? - Люди предпочитают сокращения и сокращенные имена длинным именам?
20 ответов
Лично я бы НАМНОГО видел более длинные имена, которые на самом деле что-то значат, без необходимости сначала определять контекст. Конечно, переменные, которые не имеют реального значения, такие как счетчики, я все еще использую маленькие бессмысленные имена переменных (такие как i или же x), но в остальном многословие - это ясность в большинстве случаев. Это особенно верно для общедоступных API.
Это может быть слишком далеко, однако. Я видел какой-то код VB в прошлом таким смешным. Модерация как и все остальное!
Я на самом деле использую длинные имена переменных все время, после того, как все современные IDE и текстовые редакторы завершены, так что нет ничего плохого в использовании index вместо этого, если я. Единственное исключение, которое у меня есть, это когда дело касается координат б / у x а также y иметь больше смысла там.
Переменной должно быть присвоено самое короткое имя, которое адекватно отражает ее назначение.
Излишняя многословность имеет тенденцию скрывать синтаксис, и синтаксис важен.
Во всей программе (или приложении / системе) переменные должны именоваться с единообразным стилем, а похожие вещи должны называться одинаково. Если в языковом сообществе существует соглашение, его следует соблюдать (так что не используйте camelCaseRubyVariableNames), если нет веских причин не делать этого.
Сокращения, если они используются, должны применяться повсеместно, а если они специфичны для конкретной области, должны где-то записываться. Если кто-то собирается потратить какое-то полезное количество времени с кодом, он скоро узнает.
Если вам нужно объединить целых пять или шесть слов для именования переменной, то я бы посоветовал вам взглянуть на запах кода, и рутина, над которой вы работаете, может выиграть от небольшой работы.
В основном, однако, если вы знаете о подводных камнях и действительно думаете о том, что пишете, есть вероятность, что ваш код будет разумным. Представьте, что вы описываете функцию, над которой вы работаете, новому коллеге - чем меньше вы думаете, что вам нужно будет сказать, тем лучше, вероятно, код.
Попробуйте прочитать свой собственный код 1 год спустя. Вы увидите как значение самодокументируемых имен переменных, так и значение комментариев к коду (и особенно значение чистого кода)
Когда вы берете чужой исходный код и не понимаете его, легко подумать: "Ну, он не такой хороший программист, как я". Но когда вы понимаете, что ваш собственный код трудно читать, вы начинаете понимать: thinkng?"
В долгосрочной перспективе многословие помогает ремонтопригодности. Для короткого однострочного скрипта вы все равно можете использовать "setLocNm" вместо setLocationName "
Любой дурак может написать код, понятный компьютеру. Хорошие программисты пишут код, понятный людям. -Мартин Фаулер
Лично я нахожу многословие хорошей вещью, но слишком легко быть слишком многословным, что плохо. Существует баланс, и сокращения могут также входить в этот баланс.
Это мои общие правила:
- Итераторы могут быть одной буквой, т.е.
i,j,k, так далее. - Другие переменные одного слова, такие как булевы переключатели, что у вас никогда не сокращается, т.е.
installing,done, так далее. - Переменные из нескольких слов и имена функций являются кандидатами на аббревиатуру, но только в том случае, если они начинают слишком долго (скажем, 20-25+ символов). Интеллектуальное сокращение является ключом здесь.
function => funcнапример, но никогдаfun,f, или жеfuncti
Я просмотрел ответы, но не вижу, покрыто ли следующее. Вот и все...
Если вы сокращены или многословны, просто убедитесь, что вы использовали не больше слов, чем необходимо, и значение этого чертовски очевидно.
Но даже после этой фильтрации, если ваши идентификаторы выглядят многословно, у вас есть недостаток в вашем дизайне.
def initialize_report_template()
end
должно было...
class ReportTemplate
def initialize()
end
end
Я думаю, что можно сокращать, когда имя ухудшает читабельность или просто лишнее.
Пример 1. Аргумент метода, в котором тип уже передает всю необходимую информацию.
Пример 2: переменная, которая будет много использовать очевидным образом
StringBuilder sb = ...
sb.append(...
sb.append(...
return sb.toString();
Пример 3: идиоматические сокращения. i,j,k уже упоминалось. "sb" выше - это один в нашем коде, и у каждой команды, вероятно, есть еще пара.
Длинные имена намного лучше. Вы упоминаете, что вы часто видите сокращенные имена в небольших областях. Кто сказал, что объем будет оставаться небольшим по мере роста программного обеспечения?
Конечно, XCoordinateForCurrentLocationOfSelf - это смешное имя, так что будьте разумны. Особенно если вы входите в проект, над которым вы раньше не работали, вы будете благодарны всем, кто использовал описательные функции и имена переменных.
Стремитесь к короткому, а не длинному, но понимание читателя должно превзойти лень печатать каждый раз.
Как уже говорили другие, длина имени переменной не должна заслонять логику или алгоритм. Например, в арифметике мы пишем
( 1 + 5 ) * 3 = 18
скорее, чем
three multiplied by the sum of one and five equals eighteen
потому что мы пытаемся привлечь внимание к другим вещам, кроме ясности элементов, участвующих в выражении.
Я склонен держать переменные от одного до трех слов, сокращая их, только если я превышаю 24 символа или около того. Чем реже используется переменная, тем больше у меня шансов сделать имя переменной длинным. Более часто используемые переменные я сделаю короче.
Макс Канат-Александр, главный архитектор Bugzilla, говорит об этом в своем блоге:
Сам код должен занимать место пропорционально тому, как много он имеет значения.
По сути, крошечные символы, которые много значат, затрудняют чтение кода. Очень длинные имена, которые ничего не значат, также затрудняют чтение кода. Количество смысла и занимаемое пространство должны быть тесно связаны друг с другом.
http://www.codesimplicity.com/post/readability-and-naming-things/
Это очень проницательный пост о наименовании вещей. Я призываю всех прочитать это!
Я согласен с Килхоффером; Я предпочитаю видеть описательные имена переменных практически в каждом контексте. Я буду сокращать, если мои имена переменных будут длиннее 20 символов или около того, обычно со словами в имени переменной (например: "SomeVeryLongVarValue").
Конечно, я также использую венгерскую нотацию всякий раз, когда могу, поэтому я вполне могу оказаться в другом крайнем лагере, пытаясь сделать имена переменных слишком описательными, в зависимости от вашей перспективы.
Единственный раз, когда я принимаю сокращения, это для локальных переменных, которые находятся в области действия только в течение небольшого периода времени.
Это означает, что они должны входить в область видимости с очень читаемым методом или конструктором.
Я, вероятно, буду полностью освистан, но я хотел убедиться, что это мнение было услышано.
Хотя более длинные имена переменных могут быть более наглядными, они могут начать отражать первоначальные намерения программы. Я чувствую, что для элементов API важно иметь четкие и значимые имена в контексте, в котором они будут использоваться.
Внутри каждой функции или метода это часто другая история. Я стараюсь писать меньше и очень лаконично. Это известно как спартанское программирование и мистер Этвуд, и это отличный пример. Да, пример явно сфальсифицирован, но он демонстрирует, как немного меньше церемоний может на самом деле облегчить чтение программы.
Удачи.
Я думаю, что основная проблема с аббревиатурами заключается в том, что не все люди сокращаются одинаково, поэтому, когда вы работаете со многими людьми, это только может увеличить вероятность ошибки при кодировании. Например, если у вас есть константа, которую можно назвать SOMETHING_INTERFACE, возможно, некоторые разработчики будут сокращать ее как SOMETHING_INTFACE, другие - как SOMETHING_IFACE или SOMETHING_IF, SMTHING_IFACE...
Только с двумя словами вы можете иметь по крайней мере полдюжины более или менее "логических" возможных сокращений, поэтому я думаю, что в большинстве случаев лучше писать без сокращений и с большим количеством причин, если вы хотите иметь самодокументированный код,
Очень длинные имена иногда могут раздражать, но также могут быть сокращены в очень локальных областях, используя вспомогательные переменные.
У большинства людей зрение читается. Больше не нужно читать слово, а потом читать отдельное письмо. Поэтому всегда используйте значимые имена. Должны ли они быть полными 7 словами описания, нет, но они должны быть достаточно длинными, чтобы понять.
Я мог бы принять add_loc(имя, координата), так как они достаточно длинные, я могу сказать, что они есть. В add_loc(n, x, y) я бы возражал против 'n' вместо имени. Я мог бы жить с X и Y, так как это принятые названия координат.
Для кого-то, не знакомого с системами координат, я мог видеть, где add_location(имя, координаты) будет более значимым.
В случае сомнений используйте более длинные имена.
"Это нормально, чтобы выяснить тайны убийства, но вам не нужно выяснять код. Вы должны быть в состоянии прочитать его". - Стив Макконнелл
Тем не менее, если вы считаете, что ни вам, ни кому-либо другому нужны слишком явные имена переменных и т. Д., Не стесняйтесь сокращать их.
При программировании вы используете синтаксис, чтобы люди могли его читать, длина имен переменных, методов и т. Д. Действительно не имеет значения.
Чем более многословно, тем лучше, обычно, с хорошей средой разработки у вас должно быть завершение кода, поэтому вы можете просто нажать "add_L"+TAB, чтобы завершить вызов метода.
Я предлагаю принять минималистский подход. Используйте как можно меньше, следя за тем, чтобы ваш код оставался ясным, лаконичным и понятным.
Такие вещи, как константы и глобальные переменные, должны иметь длинные описательные имена. Иногда действительно длинное имя заставляет его "пахнуть" настолько, чтобы сигнализировать о его присутствии как о нежелательном. Это хорошо, потому что это будет 1 - заставлять людей избегать этого, 2 - увеличивать давление, чтобы реорганизовать код и заставить его исчезнуть.