Есть ли отношение кода/комментария, которое вы считаете признаком хорошего (плохого) кода здоровья?
Можете ли вы привести примеры проектов с открытым исходным кодом, которые считаются хорошо закодированными и их соответствующий коэффициент комментариев?
(Я понимаю, что ни одно соотношение не является "истинным" для каждого проекта, и вполне могут быть дрянные проекты, которые демонстрируют это теоретическое золотое соотношение. Тем не менее...)
Комментарии должны быть очень редкими и ценными, почти всегда выражающими "почему" и никогда не "как" (исключение - когда сложность и непрозрачность из кода).
Каждый комментарий - это подсказка, что вам может понадобиться рефакторинг, чтобы сделать код более понятным. Каждый комментарий может стать устаревшим, как только он будет написан.
У нас почти нет комментариев помимо комментариев XML в нашем xUnit.net, но некоторые люди, похоже, находят код понятным и легко читаемым.:)
Тот, кто должен исправить код от другого программиста, скажет как можно больше комментариев. Большая проблема со старым кодом: "Вы видите, что делает код. Вы видите, что это проблема. Но вы не знаете, почему программист написал это так".
Чтобы понять ошибку, которую вам нужно знать:
Мы имеем отношение 2-3%, что слишком мало. Я думаю, что 10% хороши для крупных или долгоживущих проектов.
Извините, нет эмпирического правила. Рамки и библиотеки для каждого экземпляра требуют гораздо больше комментариев, потому что программисты будут клиентами и не имеют времени на чтение кода каждый раз, когда им нужно вызвать метод.
Проекты, в которых вы пишете/читаете код, нуждаются в меньшем количестве комментариев и должны пытаться улучшить читаемость кода вместо соотношения комментариев и кодов.
С уважением
Комментарии не просто объясняют код - они также помогают отладчику, который ищет фрагмент кода, который что-то делает.
Извлечение истории заказа клиента или вычисление видимости противника может привести к десяткам строк кода, и даже эксперт-программист может занять несколько минут, чтобы быть уверенным в том, что он делает. Комментарий, который говорит "получить историю заказов клиентов", позволяет отладчику вообще не исследовать этот код, если он знает, что история заказов не является проблемой.
Я прокомментирую все, что я думаю, неоднозначно или должен быть объяснен. Часто я перечитываю комментарий. Зачем? Потому что вы никогда не знаете, кто будет работать над вашим кодом. Мне нравится представлять ситуацию, когда они заменяют половину команды обезьянами, которые понимают только, что, когда они нажимают на линию, они получают банан. Итак, если они хотя бы научатся читать, они не изменят мою логику, не прочитав сначала комментарии.
Случай и точка:
// Delete the helloworld file
exec("rm -f helloworld.txt")
Не будет изменено на:
exec("rm -rf /")
Вряд ли, я знаю, но даже некоторые хорошие разработчики, как известно, меняют логику, потому что это выглядит неправильно, а не потому, что произошла ошибка или изменение требований.
Я думаю, каждый может согласиться с тем, что 0 комментариев обычно можно рассматривать как поддокументированный код. Помните, что даже самый самодокументирующий код может только документировать, что там; никогда не было намеренно упущено, оптимизировано, пробовано и отброшено и т.д. У вас всегда будет потребность в английском, в основном, в ваших исходных файлах, или вы обязательно оставите важные оговорки и проектные решения.
Мне интересно, как эти звуковые принципы, которые вы, ребята, выступаете (с которыми я до сих пор согласен), переводятся в статистику кода. В частности, какие проекты с открытым исходным кодом считаются хорошо (не перегруженными) документально, и каково отношение комментариев.
LOC / LOcomment = yearsofexp / 5
У меня очень простое правило: если вам нужно остановиться и подумать более ~ 15 секунд при кодировании некоторого фрагмента кода (скажем, функции или сложного цикла и т.д.), то этот фрагмент кода требуется комментарий.
Это действительно хорошо для меня. В следующий раз, когда вы, или кто-то на вашем уровне понимания общей базы кода, столкнется с этим фрагментом кода, он сразу увидит , почему было сделано так, как оно было сделано.
Мое правило таково: если есть что-то, что нужно сказать, а код не может быть выражен, то вы можете написать комментарий. В противном случае, если код может выразить идею, тогда вы должны выразить идею в коде или его тестах.
Если вы следуете этому правилу, тогда вашему коду должны понадобятся комментарии только в том случае, если он имеет дело с некоторой неочевидной проблемой в аппаратной или операционной системе или когда наиболее очевидным алгоритмом является не лучший выбор. Это "это странно, потому что" комментирует, и на самом деле это всего лишь механизм преодоления. Большинство комментариев времени в коде - это просто извинения за то, что вы не пишете его более очевидным образом, и такие комментарии должны быть устранены, а затем удалены.
Даже хорошие комментарии часто становятся ложью с течением времени, поэтому информация в неисполняемых, не проверяемых местах, таких как комментарии, должна быть озадачена подозрением. Опять же, ответ заключается в том, чтобы сначала удалить комментарий, а затем удалить его.
Мое идеальное соотношение равно нулю. Тем не менее, мир менее идеален, поэтому я принимаю комментарии, когда нет другого способа сообщить важную идею.
Там должны быть комментарии, где вы считаете их необходимыми. Не больше и не меньше.
Прокомментируйте те части, которые, по вашему мнению, вы не понимаете после 6 + недельного перерыва при повторном просмотре кода
Нет золотого отношения. Количество комментариев сильно зависит от присущей сложности кода. Если вы просто пишете CRUD-приложения, вам, вероятно, не нужно много комментариев. Если вы пишете операционную систему или RDBMS, вам, вероятно, придется прокомментировать больше, так как вы будете делать более сложное кодирование, и вам нужно будет сделать более понятным, почему вы делаете то, что делаете.
Я стараюсь держать комментарии как минимум. Код должен быть самообучающимся, и хотя исходный код имеет тенденцию к изменению комментариев, почти всегда остается позади как неправильное объяснение.
Коэффициент золотого кода/комментария - это пересечение
Это также показывает, почему это соотношение отличается для каждого проекта и каждой команды.
Я не думаю, что кто-то может дать вам цифры, но он должен быть намного выше в файлах заголовков, чем в источнике.
Я ожидаю, что заголовочный файл для класса будет документировать все доступные классы/функции/и т.д., включая этот заголовочный файл. Это может быть довольно много строк для документирования функции, прототип которой представляет собой одну строку (нет, просто выбрать хорошие имена для функций и их параметров недостаточно - это может быть, но часто это не так). Три строки комментариев для каждой строки кода не будут чрезмерными.
Для фактического кода это будет намного ниже. Я не согласен с экстремистами, которые думают, что вы должны стремиться к нулевым комментариям, но, конечно, если вы считаете, что вам нужны комментарии, вы должны сначала рассмотреть, можно ли сделать код более понятным.
Это может варьироваться совсем немного. Например, у вас может быть хорошо написано, что комментарии будут просто пустой тратой времени.
Вам нужно достаточно комментариев, так что через несколько месяцев вы сможете посмотреть на свой код, прочитать комментарий и просто подобрать то место, где вы остановились, без особых усилий. Если история жизни кода не требуется, не пишите.
Нет такого понятия, как хороший комментарий к коду. В прежние времена некоторые люди считали, что вам нужно иметь во внимание каждую функцию, объясняющую, что она делает.
Однако с появлением современных языков код в значительной степени самодокументируется. Это означает, что единственные причины, по которым оставлять комментарий в коде, - это либо объяснить, откуда взялось какое-то решение, либо помочь понять действительно сложный вопрос.
Нет "золотого отношения". Это зависит от языка и способа его написания. Чем более выразителен ваш код, тем больше он может быть самодокументирован - и, следовательно, меньше комментариев вам нужно. Это одно преимущество плавного интерфейса.
Вы не можете указать фиксированный коэффициент кода/комментариев, иначе вы закончите с кодом, связанным с шумом вроде:
// Add one to i
i++;
который просто облакает код.
Вместо этого посмотрите на сложность кода и посмотрите, что вам нужно объяснить, т.е. разумно логику, почему используются некоторые магические числа, какие предположения присутствуют в отношении входящих форматов и т.д.
Включите мышление ваших сторонников и подумайте, что бы вы хотели увидеть в отношении кода, который вы только что написали.
НТН.
веселит,
Rob
Комментарии имеют 3 использования, IMO:
Если код делает что-то достаточно, чтобы понять, почему это понятно, что должно быть в большинстве случаев в большинстве доменов, тогда комментарии в логике должны быть минимальными... даже не приближаясь ни к одному. Комментарии никогда не должны объяснять, что (с возможными исключениями сказать, например, что функция является реализацией алгоритма Foo, как объясняется в публикации Bar). Если вам нужно объяснить, что вы делаете, вы делаете это плохо.
Существует отличное обсуждение кодовых комментариев в книге Стив Макконнеллс() Code Complete (у меня есть первое издание, но я считаю, что теперь второе издание link текст)
В целом, это усиливает то, что было сказано другими ответами, - должно быть редкими и описывать, почему бы и нет, - если вы можете реорганизовать имена переменных и методов для замены комментариев, то это должно быть заранее - с большинством IDE, предлагающим какой-то intellisense ( или как я когда-то слышал, что Don Box описывает это как - intellicrack из-за его adictivness), нет причин усекать имена переменных/методов, когда более длинная более ясная версия будет более четко сообщать о своем намерении
0/0 ; zero divided by zero
Runtime error (func=(main), adr=3): Divide by zero
подразумеваемая команда "Do What я Mean" с комментарием "no comment"?
Если вам нужны данные реального мира о соотношении комментариев для разных языков, посмотрите Ohloh.
В качестве примера вы можете посмотреть различные показатели для источника ядра Linux.
Нет такого отношения.
Обычно комментарии должны присутствовать только в ситуациях, когда что-то может быть непонятно, например
// Do not Dispose!
SPSite site = properties.Feature.Parent as SPSite;
С другой стороны, если вы продаете Код кому-то, ему потребуется как можно больше комментариев. Обработка изображений 3D-движком или другими промежуточными продуктами Games, в которых нет комментариев. Конечно, API-документация и т.д. Также являются важной частью такого промежуточного программного обеспечения, но хороший код с комментариями также окупается. Такие вещи, как "Добавить 1 в i", все еще слишком spammy, но что-то вроде "CreateDevice() будет сначала проверять, доступен ли DirectX 10 и вернуться к устройству DirectX 9, если нет", может быть действительно полезно, даже если это тривиально см. код.
Как правило, внутренний код обычно намного меньше комментариев, чем код, который вы продаете, но могут применяться исключения.
Мне нравится использовать комментирование для аннотирования кода, который я уверен, легко читаем и имеет информационные переменные. При этом я хотел бы попытаться написать каждую строку кода как можно более информативный, чем комментарий. Вы должны иметь очень сильный смысл в том, что делает код, прежде чем читать комментарии, или вы делаете это неправильно.
между 3% и 9,5%, более или менее
Я должен сказать, что я пришел сюда, чтобы найти ответ на 2 комментария на 1 строку кода. Даже если это преувеличение, это в правильном направлении! Вместо этого я вижу, что люди рекомендуют обрабатывать комментарии, такие как трюфели или другой редкий товар. Если взглянуть на своеобразную перспективу академических кругов, качество кода низкое, а использование контроля версий еще реже, чем трюфели, я хотел бы призвать кого-либо написать как можно больше комментариев, даже против вашего собственного мнения о том, нужен ли комментарий на 100%.
Комментарии облегчают вашу жизнь, потому что, скорее всего, вы собираетесь думать, какого черта я думал при написании этого!