Как "самодокументирующийся" может кодировать, не раздражая?

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

Помогает ли читаемость читабельности, или это просто повредит всем глазам? - Люди предпочитают сокращения и сокращенные имена более длинных имен?

Ответ 1

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

Это может занять слишком много времени. Я видел, что в прошлом код VB был смешным. Модерация, как и все остальное!

Ответ 2

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

Ответ 3

Никогда не abbr.

Ответ 4

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

Over-verbosity имеет тенденцию скрывать синтаксис, и синтаксис важен.

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

Сокращения, если они используются, должны быть последовательно применены повсюду и, если они специфичны для домена, должны быть записаны где-то. Если кто-то собирается потратить какое-то полезное количество времени на код, то они скоро узнают.

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

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

Ответ 5

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

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

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

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

Ответ 6

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

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

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

Ответ 7

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

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

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

def initialize_report_template()
end

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

class ReportTemplate
    def initialize()
    end
end

Ответ 8

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

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

Ответ 9

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

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

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

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

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

Ответ 10

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

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

( 1 + 5 ) * 3 = 18

а не

three multiplied by the sum of one and five equals eighteen

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

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

Ответ 11

Макс Канат-Александр, главный архитектор Бугзиллы, говорит об этом в своем блоге:

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

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

http://www.codesimplicity.com/post/readability-and-naming-things/

Это очень проницательный пост об именовании вещей. Я призываю всех прочитать его!

Ответ 12

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

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

Ответ 13

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

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

Ответ 14

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

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

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

Удачи.

Ответ 15

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

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

Ответ 16

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

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

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

Ответ 17

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

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

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

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

Ответ 18

"Это нормально, чтобы выяснить тайны убийства, но вам не нужно вычислять код. Вы должны быть в состоянии прочитать его". - Стив К. Макконнелл

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

Ответ 19

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

Ответ 20

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