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