Каково соотношение "золотой код / комментарий"?[закрыто]

Question

Существует ли соотношение код / комментарий, которое вы считаете признаком хорошего (плохого) состояния кода?

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

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

Answer 1

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

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

У нас почти нет комментариев, кроме XML-комментариев в нашем xUnit.net проект, но некоторые люди похоже, вы находите код понятным и легким для чтения.:)

Answer 2

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

Чтобы понять, в чем ошибка, вам нужно знать:

• что следует код делает (не что код делает) и почему.
• Контракт на выполнение каждой функции.Например, если существует исключение NullPointerException, то где ошибка?В функции или в вызывающей функции?
• При каждом взломе должно быть описано, как проблема может быть воспроизведена (Языковая версия, операционная система, версия операционной системы).Например, у нас есть много взломов для старой виртуальной машины Java, которая больше не поддерживается.Но мы не уверены, сможем ли мы это удалить, потому что мы не знаем, как их воспроизвести.

У нас это соотношение составляет 2-3%, что слишком мало.Я думаю, что 10% - это хорошо для крупных или долгоживущих проектов.

Answer 3

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

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

С наилучшими пожеланиями

Answer 4

Комментарии не просто объясняют код - они также направляют отладчик, который ищет фрагмент кода, который что-то делает.

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

Answer 5

Я комментирую все, что, по моему мнению, неоднозначно или должно быть объяснено.Часто я чрезмерно комментирую.Почему?Потому что вы никогда не знаете, кто будет работать над вашим кодом.Мне нравится представлять ситуацию, когда они заменяют половину команды обезьянами, которые понимают только то, что когда они нажимают enter в строке, они получают банан.Так что, если они хотя бы научатся читать, они не изменят мою логику, не прочитав сначала комментарии.

Случай и точка зрения:

// Delete the helloworld file
exec("rm -f helloworld.txt")

Не будет заменен на:

exec("rm -rf /")

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

Answer 6

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

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

Answer 7

У меня есть очень простое эмпирическое правило:Если вам нужно остановиться и подумать более ~ 15 секунд при написании какого-либо фрагмента кода (скажем, функции или сложного цикла и т.д.), то этот фрагмент кода нуждается в комментарии.

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

Answer 8

LOC / LOcomment = yearsofexp / 5

Answer 9

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

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

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

Мое идеальное соотношение равно нулю.Однако мир далек от идеала, поэтому я принимаю комментарии, когда нет другого способа донести важную идею.

Answer 10

Там должны быть комментарии там, где вы считаете их необходимыми.Не больше и не меньше.

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

Answer 11

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

Answer 12

Золотое соотношение кода и комментария - это пересечение

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

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

Answer 13

Здесь нет золотого сечения.Количество комментариев во многом зависит от присущей коду сложности.Если вы просто пишете CRUD-приложения, вам, вероятно, не нужно много комментариев.Если вы пишете операционную систему или СУБД, вам, вероятно, потребуется больше комментариев, поскольку вы будете выполнять более сложное кодирование, и вам нужно будет немного более четко объяснить, почему вы делаете то, что делаете.

Answer 14

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

В качестве примера вы можете посмотреть на различные показатели для исходного кода ядра Linux.

Answer 15

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

Я бы ожидал, что заголовочный файл для класса будет документировать все классы / функции / etc, доступные для общего доступа, включая этот заголовочный файл.Это может быть довольно много строк для документирования функции, прототипом которой является одна строка (нет, простого выбора подходящих имен для функций и их параметров недостаточно - это может быть, но часто это не так).Три строки комментария для каждой строки кода не будут чрезмерными.

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

Answer 16

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

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

Answer 17

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

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

Answer 18

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

Answer 19

Вы не можете установить фиксированное соотношение код / комментарии, иначе в итоге вы получите код, пронизанный шумом, например:

// Add one to i
i++;

что просто затуманивает код.

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

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

ХТХ.

ваше здоровье,

Роб

Answer 20

Комментарии имеют 3 применения, IMO:

• Объясните почему код делает то, что он делает
• Документируйте интерфейс для модуля
• Объясните, почему не были использованы другие подходы к фрагменту логики

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

Answer 21

Отличное обсуждение комментариев к коду есть в книге Стива Макконнеллса () Code Complete (у меня есть первое издание, но я полагаю, что сейчас вышло второе издание текст ссылки)

Таким образом, это подтверждает то, что указано в других ответах - должно быть редким и описывать, почему, а не как - если вы можете реорганизовать имена переменных и методов для замены комментариев, то это должно быть предпочтительнее - поскольку большинство IDE предлагают какой-то intellisense (или, как я однажды слышал, Don Box описывает это как - intellicrack из-за его adictivness), нет причин усекать имена переменных / методов, когда более длинная и понятная версия более четко сообщала бы о своем намерении

Answer 22

0/0 ; zero divided by zero
Runtime error (func=(main), adr=3): Divide by zero

подразумеваемая команда "Делай то, что я имею в виду" с комментарием "без комментариев"?

Answer 23

Такого соотношения не существует.

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

// Do not Dispose!
SPSite site = properties.Feature.Parent as SPSite;

С другой стороны, если вы продаете кому-то код, для этого потребуется как можно больше комментариев.Imaging продает 3D-движок или какое-либо другое программное обеспечение промежуточного уровня для Игр, которое не имеет комментариев.Конечно, документация по API и т.д.они также являются большой частью такого промежуточного программного обеспечения, но хороший прокомментированный код также окупается.Такие вещи, как "Добавить 1 к i", все еще слишком спамны, но что-то вроде "CreateDevice() сначала проверит, доступен ли DirectX 10, и вернется к устройству DirectX 9, если нет", может быть действительно полезным, даже если это тривиально увидеть из кода.

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

Answer 24

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

Answer 25

от 3% до 9,5%, более или менее

Answer 26

Я должен сказать, что я пришел сюда в поисках ответа примерно на 2 комментария на 1 строку кода.Даже если это преувеличение, оно в правильном направлении!Вместо этого я вижу, что люди рекомендуют относиться к комментариям как к трюфелям или другому редкому товару.Глядя со своеобразной точки зрения академических кругов, если качество кода низкое, а использование контроля версий встречается еще реже, чем truffles, я бы настоятельно призвал всех писать как можно больше комментариев, даже вопреки вашему собственному суждению о том, является ли комментарий необходимым на 100%.

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