Как “самодокументирование” код может быть, не будучи раздражающим? [закрытый]

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

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

"Нормально выяснять детективы, но Вы не должны должны быть выяснять код. Необходимо смочь считать его". - Steve C. McConnell

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

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

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

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

, Когда в сомнении, используйте более длинные имена.

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

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

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

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

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

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

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

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

Удача.

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

Значение они должны входить в объем с очень читаемым методом или конструктором.

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

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

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

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

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

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

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

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

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

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

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

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

def initialize_report_template()
end

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

class ReportTemplate
    def initialize()
    end
end

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

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

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

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

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

В конечном счете многословие помогает пригодности для обслуживания. Если коротко, один сценарий строки, можно все еще использовать "setLocNm" вместо setLocationName"

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

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

Сверхмногословие имеет тенденцию скрывать синтаксис, и синтаксис важен.

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

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

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

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

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

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

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

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

( 1 + 5 ) * 3 = 18

, а не

three multiplied by the sum of one and five equals eighteen

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

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