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

Я только что понял, просто нужно добавить свойство height в реквизит :init, например:

<editor api-key="myapikey" :init="{plugins: 'wordcount',height: 500}"></editor>
23
задан 3 revs, 2 users 63% 21 September 2008 в 19:22
поделиться

25 ответов

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

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

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

41
ответ дан 29 November 2019 в 00:38
поделиться

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

0
ответ дан 29 November 2019 в 00:38
поделиться

Нет такого отношения.

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

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

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

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

0
ответ дан 29 November 2019 в 00:38
поделиться
0/0 ; zero divided by zero
Runtime error (func=(main), adr=3): Divide by zero

подразумеваемая команда "Do What I Mean" с "никаким комментарием" комментарий?

0
ответ дан 29 November 2019 в 00:38
поделиться

Существует превосходное обсуждение комментариев к коду в Steve McConnells () книжный Завершенный Код (у меня есть первый выпуск, но я верю, теперь второй текст ссылки выпуска )

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

0
ответ дан 29 November 2019 в 00:38
поделиться

Комментарии имеют 3 использования, IMO:

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

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

0
ответ дан 29 November 2019 в 00:38
поделиться

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

// Add one to i
i++;

, который просто объединяет код в облако.

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

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

HTH.

аплодисменты,

Rob

0
ответ дан 29 November 2019 в 00:38
поделиться

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

0
ответ дан 29 November 2019 в 00:38
поделиться

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

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

0
ответ дан 29 November 2019 в 00:38
поделиться

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

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

0
ответ дан 29 November 2019 в 00:38
поделиться

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

Как пример, можно посмотреть различные метрики для источника Ядра Linux.

1
ответ дан 29 November 2019 в 00:38
поделиться

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

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

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

1
ответ дан 29 November 2019 в 00:38
поделиться

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

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

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

1
ответ дан 29 November 2019 в 00:38
поделиться

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

1
ответ дан 29 November 2019 в 00:38
поделиться

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

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

2
ответ дан 29 November 2019 в 00:38
поделиться

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

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

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

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

3
ответ дан 29 November 2019 в 00:38
поделиться
LOC / LOcomment = yearsofexp / 5
4
ответ дан 29 November 2019 в 00:38
поделиться

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

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

4
ответ дан 29 November 2019 в 00:38
поделиться

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

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

5
ответ дан 29 November 2019 в 00:38
поделиться

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

Случай и точка:

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

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

exec("rm -rf /")

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

7
ответ дан 29 November 2019 в 00:38
поделиться

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

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

7
ответ дан 29 November 2019 в 00:38
поделиться

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

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

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

7
ответ дан 29 November 2019 в 00:38
поделиться

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

Для понимания ошибки необходимо знать:

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

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

23
ответ дан 29 November 2019 в 00:38
поделиться

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

1
ответ дан 29 November 2019 в 00:38
поделиться

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

0
ответ дан 29 November 2019 в 00:38
поделиться
Другие вопросы по тегам:

Похожие вопросы: