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