Насколько "самодокументируемым” может быть код, не вызывающий раздражения?[закрыто]
https://stackoverflow.com/questions/214160
-
03-07-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianВопрос
Я не уверен, какие здесь рекомендации, но я часто вижу сокращенные имена переменных, особенно когда область действия невелика.Итак (чтобы использовать простые примеры Ruby) вместо def add_location(name, coordinates), Я вижу такие вещи , как def add_loc(name, coord)—и я мог бы даже увидеть что-то вроде def add_loc(n, x, y). Я полагаю, что более длинные имена могут утомить человека, когда он привык видеть аббревиатуры.
Способствует ли многословие удобочитаемости или это просто режет всем глаза?— Люди предпочитают аббревиатуры и сокращенные имена более длинным?
Решение
Лично я бы НАМНОГО видел более длинные имена, которые на самом деле что-то значат, без необходимости сначала определять контекст. Конечно, переменные, которые не имеют реального значения, такие как счетчики, я все еще использую маленькие бессмысленные имена переменных (например, i или x ), но в остальном многословие - это ясность большую часть времени. Это особенно верно для общедоступных API.
Однако это может быть слишком далеко. Я видел какой-то код VB в прошлом таким смешным. Модерация как и все остальное!
Другие советы
Я на самом деле все время использую длинные имена переменных, после того, как все современные IDE и текстовые редакторы имеют завершение, поэтому нет ничего плохого в использовании index вместо i, если я. Единственное исключение, которое у меня есть, - это когда дело касается координат b / c x и y . Здесь больше всего смысла.
Никогда не сокращайся.
Переменной должно быть присвоено самое короткое имя, которое адекватно отражает ее назначение.
Излишнее многословие имеет тенденцию скрывать синтаксис, и синтаксис важен.
Во всей программе (или приложении / системе) переменные должны именоваться с единообразным стилем, а похожие вещи должны называться одинаково. Если в языковом сообществе существует соглашение, его следует соблюдать (поэтому не используйте camelCaseRubyVariableNames), если только для этого нет веских причин.
Сокращения, если они используются, должны применяться повсеместно, а если они специфичны для конкретного домена, должны быть где-то записаны. Если кто-то собирается потратить какое-то полезное количество времени с кодом, он скоро узнает.
Если вам нужно объединить до пяти или шести слов для именования переменной, я бы посоветовал вам взглянуть на запах кода и рутина, с которой вы работаете, может принести пользу от небольшой работы.
В основном, если вы знаете о подводных камнях и действительно думаете о том, что вы пишете, есть вероятность, что ваш код будет разумным. Представьте, что вы описываете функцию, над которой вы работаете, новому коллеге - чем меньше вы думаете, что вам нужно будет сказать, тем лучше, вероятно, код.
Попробуйте прочитать свой собственный код спустя 1 год. Вы увидите как значение самодокументируемых имен переменных, так и значение комментариев к коду (и особенно значение чистого кода)
Когда вы берете чей-то другой исходный код и не понимаете его, легко подумать "Ну, он не такой хороший программист, как я" Но когда вы понимаете, что ваш собственный код трудно читать, вы начинаете говорить: «Что я думаю?»
В долгосрочной перспективе многословие помогает ремонтопригодности. Для короткого однострочного сценария вы все равно можете использовать "setLocNm" вместо setLocationName "
Любой дурак может написать код, понятный компьютеру. Хорошие программисты пишут код, понятный людям. -Martin Fowler
Лично я нахожу многословие хорошей вещью, но легко быть и чрезмерно многословным, а это плохо.Существует баланс, и аббревиатуры тоже могут входить в этот баланс.
Таковы мои общие правила:
- Итераторы могут состоять из одной буквы, т.е.
i,j,k, и т.д. - Другие однословные переменные, такие как логические переключатели, которые у вас никогда не сокращаются, т.е.
installing,done, и т.д. - Переменные с несколькими словами и имена функций являются кандидатами на сокращение, но только в том случае, если они начинают становиться чрезмерно длинными (скажем, более 20-25 символов).Ключевым моментом здесь является разумная аббревиатура.
function => funcнапример, но никогдаfun,f, илиfuncti
Я просмотрел ответы, но не вижу, покрыто ли следующее. Вот и все ...
Независимо от того, сокращены вы или многословны, просто убедитесь, что вы использовали не больше слов, чем необходимо, а их значение чертовски очевидно.
Но даже после этой фильтрации, если ваши идентификаторы выглядят многословно, у вас есть недостаток в дизайне.
def initialize_report_template()
end
должен был быть ...
class ReportTemplate
def initialize()
end
end
Длинные имена намного лучше. Вы упоминаете, что вы часто видите сокращенные имена в небольших областях. Кто скажет, что объем будет оставаться небольшим по мере роста программного обеспечения?
Конечно, XCoordinateForCurrentLocationOfSelf - это смешное имя, так что будьте разумны. Особенно, если вы входите в проект, над которым вы раньше не работали, вы будете благодарны всем, кто использовал описательные функции и имена переменных.
Я думаю, что можно сокращать, если имя ухудшает читабельность или просто лишнее.
Пример 1. Аргумент метода, в котором тип уже передает всю необходимую информацию.
Пример 2: переменная, которая будет много использовать очевидным образом
StringBuilder sb = ...
sb.append(...
sb.append(...
return sb.toString();
Пример 3: идиоматические сокращения. i, j, k уже упоминалось. & Quot; СО & Quot; выше один в нашем коде, и у каждой команды, вероятно, есть еще пара.
Стремитесь к более короткому, а не к более длинному, но понимание читателя должно быть козырем noreferrer "> лень печатать каждый раз.
Как уже говорили другие, длина имени переменной не должна заслонять логику или алгоритм. Например, в арифметике мы пишем
( 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-вещи /
Это очень проницательный пост о наименовании вещей. Я призываю всех прочитать это!
Единственный раз, когда я принимаю сокращения, это локальные переменные, которые находятся в области действия только в течение небольшого периода времени.
Это означает, что они должны входить в область видимости с очень читаемым методом или конструктором.
Я согласен с Килхоффером; Я предпочитаю видеть описательные имена переменных практически в каждом контексте. Я сокращу, если мои имена переменных будут длиннее 20 символов или около того, обычно со словами в имени переменной (например: " SomeVeryLongVarValue ").
Конечно, я также использую венгерскую нотацию всякий раз, когда могу, поэтому я вполне могу оказаться в другом крайнем лагере, пытаясь сделать имена переменных слишком описательными, в зависимости от вашей перспективы.
Возможно, меня полностью освистят, но я хотел убедиться, что это мнение было услышано.
Хотя более длинные имена переменных могут быть более наглядными, они могут начать отражать первоначальные намерения программы. Мне кажется, что для элементов API важно иметь четкие и значимые имена в контексте, в котором они будут использоваться.
Внутри каждой функции или метода это часто другая история. Я стараюсь писать меньше и очень лаконично. Это известно как спартанское программирование. Atwood и этот отличный пример. Да, пример явно сфальсифицирован, но он демонстрирует, как немного меньше церемоний может на самом деле облегчить чтение программы.
Удачи.
При программировании вы используете синтаксис, чтобы люди могли его прочитать, длина имен переменных, методов и т. д. действительно не имеет значения.
Чем более многословно, тем лучше, обычно, с хорошей средой разработки у вас всегда должно быть завершение кода, поэтому вы можете просто нажать «add_L» + TAB, чтобы завершить вызов метода.
Я думаю, что основная проблема с аббревиатурами заключается в том, что не все люди сокращаются одинаково , поэтому, когда вы работаете со многими людьми, это только может увеличить вероятность ошибки при кодировании. Например, если у вас есть константа, которую можно назвать SOMETHING_INTERFACE, возможно, некоторые разработчики будут сокращать ее как SOMETHING_INTFACE, другие - как SOMETHING_IFACE или SOMETHING_IF, SMTHING_IFACE ...
Только с двумя словами вы можете иметь как минимум полдюжины из более или менее "логики" возможные сокращения, поэтому я думаю, что в большинстве случаев лучше писать без сокращений и с большим количеством причин, если вы хотите иметь самодокументированный код.
Очень длинные имена иногда могут раздражать, но также могут быть сокращены в очень локальных областях, используя вспомогательные переменные.
Большинство людей читают зрение. Больше не нужно читать слово, а потом читать отдельное письмо. Поэтому всегда используйте значимые имена. Должны ли они быть полными 7 словами описания, нет, но они должны быть достаточно длинными, чтобы понять.
Я мог бы принять add_loc (имя, координата), так как они достаточно длинные, я могу сказать, что они есть. В add_loc (n, x, y) я бы возражал против 'n' вместо имени. Я мог бы жить с X и Y, так как это общепринятые названия координат.
Для кого-то, кто не знаком с системами координат, я мог видеть, где add_location (имя, координаты) будет более значимым.
В случае сомнений используйте более длинные имена.
" Разобраться в загадках убийства можно, но вам не нужно разбираться в коде. Вы должны быть в состоянии прочитать его. - Стив Макконнелл
Тем не менее, если вы считаете, что ни вам, ни кому-либо еще нужны слишком явные имена переменных и т. д., не стесняйтесь их сокращать.
Я предлагаю использовать минималистский подход. Используйте как можно меньше, следя за тем, чтобы ваш код оставался ясным, лаконичным и понятным.
Такие вещи, как константы и глобальные переменные, должны иметь длинные описательные имена. Иногда действительно длинное имя заставляет его «пахнуть» достаточно, чтобы сигнализировать о его присутствии как о нежелательном. Это хорошо, потому что это будет 1 - заставлять людей избегать этого, 2 - увеличивать давление, чтобы реорганизовать код, чтобы он исчез.
