Комментарии в исходном коде
Как сохранить исходный код хорошо документированным / прокомментированным? Есть ли инструмент для создания каркаса для комментариев на платформе Unix для C++?
В общем, сколько строк комментариев рекомендуется для файла с примерно 100 строками кода?
19 ответов
Как правило, лучше позволить самому коду объяснять, что он делает, тогда как комментарии есть, чтобы объяснить, почему это так. Там нет номера, чтобы придерживаться. Если ваши 100 строк говорят сами за себя, не комментируйте вообще или просто предоставьте резюме в начале. Если есть некоторые знания, которые выходят за рамки того, что делает код, объясните это в комментарии.
Если ваш код слишком сложен для объяснения, это может стать причиной для рефакторинга.
Таким образом, когда вы меняете реализацию, вам также не нужно менять комментарии, так как ваши комментарии не дублируют код. Так как причины дизайна редко меняются, для ясности можно документировать их в комментариях.
Лично я думаю, что скелетные комментарии - ужасная, ужасная идея. Я понимаю, что иногда приятно сохранить пару нажатий клавиш и, возможно, получить подписи аргументов в комментариях... но результирующие n+1 пустых бесполезных комментариев (когда редактор добавил шаблоны и кодер оставил их как есть) просто раздражают.
Я действительно думаю, что комментарии необходимы, во всяком случае - если только один код написан слишком тривиально для недопустимого объяснения, скорее всего, этот код бесполезен (то есть может быть автоматизирован и не должен быть написан от руки). Я склонен комментировать мой код достаточно хорошо, потому что я узнал, что обычно он мне сначала нужен сам. То, что другие могут использовать их, это просто дополнительный бонус.
В общем, сколько строк комментариев рекомендуется для файла с примерно 100 строками кода?
Достаточно, чтобы прояснить свое намерение и объяснить любые незнакомые идиомы. Эмпирического правила не существует, потому что нет двух одинаковых 100 строк кода.
Например, в C# свойству могут быть заданы установщики и получатели, например:
public int ID { get; set; }
Теперь я даже не видел C#, пока не присоединился к Stackru две недели назад, но это не нуждается в комментариях даже для меня. Комментируя это с
// accessor and setter for ID property
будет просто шум. Так же,
for( int i = m ; i < n; ++i) { // "loop from m to n" is a pointless comment
char* p = getP() ; // set p to getP, pure noise.
if( p ) // if p does not eqaul null, pure noise
int a &= 0x3; // a is bitwise or'd with 0x303, pure noise
// mask off all but two least significant bits,
//less noisy but still bad
// get remainder of a / 4, finally a useful comment
Опять же, любой компетентный кодер может прочитать код, чтобы увидеть, что он делает. Любой программист с базовым опытом знает, что if( p )
это общая идиома if( p != 0)
, который не нуждается в объяснении. Но никто не может прочитать ваши намерения, если вы не прокомментируете это.
Прокомментируйте то, что вы пытаетесь сделать, причину, по которой вы это делаете, а не то, что код явно делает.
При редактировании: вы заметите, что через 11 дней никто не прокомментировал преднамеренную ошибку в одном из моих примеров комментариев. Это только подчеркивает, что этот комментарий - чистый шум.
Я думаю, что у этого вопроса есть много хороших соответствующих ответов на подобный вопрос: Самодокументированный код
Что касается инструментов для создания комментариев, то это зависит от используемого вами редактора и платформы. Visual studio автоматически создает пространство для комментариев, по крайней мере иногда для C#. Есть также инструменты, которые используют комментарии для создания документации. Что касается количества строк, я думаю, что это не имеет значения. Будьте максимально лаконичны и понятны.
Мой личный идеал - писать достаточно комментариев, чтобы чтение только комментариев объясняло, как и почему функция предназначена для использования. Как это работает, обычно должно исходить из правильно выбранных имен переменных и четкой реализации.
Один из способов добиться этого, по крайней мере, на стороне комментариев, - это с самого начала использовать такой инструмент, как Doxygen. Начните кодировать каждую новую функцию, написав комментарий, описывающий, для чего она и как ее следует использовать.
Хорошо настройте Doxygen, включите генерацию документов в качестве этапа сборки и прочитайте полученную документацию.
Единственный шаблон комментария, который может быть полезен, - это набросок в самом начале блока комментариев Doxygen, но даже это может быть слишком много. Вы хотите, чтобы сгенерированная документация объясняла, что важно, не загромождая ее бесполезным заполнителем, который никогда не будет переписан.
Я думаю, что хороший совет - прокомментировать каждый класс и метод с общим описанием того, для чего они нужны, особенно если вы используете инструмент генерации HTML-документации. Помимо этого, я стараюсь сводить комментарии к минимуму - только код комментария, который потенциально может сбить с толку или потребовать интерпретации намерения. Попробуйте написать свой код так, чтобы он не требовал комментариев.
Я не думаю, что на самом деле есть метрика, которую вы можете применить к комментариям / строкам кода, это просто зависит от кода.
Это тема, которую можно довести до крайности (как и многие вещи в наши дни). Применение строгой политики иногда может привести к обесцениванию упражнения (то есть комментариев для комментариев) большую часть времени, ИМХО.
Иногда чрезмерная политика имеет смысл (например, "все публичные функции должны иметь блоки комментариев") с исключениями - зачем беспокоиться о сгенерированном коде?
Комментирование должно происходить естественно - должно дополнять читаемый код вместе со значимыми именами переменных, свойств и функций (и т. Д.).
Я не думаю, что есть полезное или точное измерение X комментариев на Y строк кода. Скорее всего, вы получите хорошее чувство баланса благодаря рецензированию (например, "этот код должен содержать комментарий, объясняющий его цель").
Я не уверен насчет инструментов автоматического комментирования для C/C++, но эквивалентом.Net должен быть GhostDoc. Опять же, эти инструменты только помогают определить структуру комментариев - значение все еще должно быть добавлено разработчиком или кем-то, кто должен интерпретировать смысл кода или дизайна.
Комментирование кода необходимо, если вы автоматически генерируете документацию (мы используем doxygen). В противном случае лучше свести его к минимуму.
Мы используем скелет для каждого метода в файле.cpp.
//**************************************************************************************************
//
/// @brief
/// @details
/// @param
/// @return
/// @sa
//
//**************************************************************************************************
но это чисто из-за наших потребностей в документации
Правила, которым я стараюсь следовать:
писать код, который автоматически документируется: хорошие и понятные имена переменных, противостоять искушению умных взломов и т. д. Этот совет во многом зависит от используемого вами языка программирования: с Python гораздо легче следовать, чем с C.
прокомментируйте в начале, чтобы направлять читателя, чтобы он сразу знал, чего ожидать.
прокомментируйте, что не очевидно из кода. Если у вас возникли проблемы с написанием фрагмента кода, это может означать, что он заслуживает комментария.
API библиотеки является особым случаем: для этого требуется документация (и часто помещать его в код - это хорошая идея, особенно с такими инструментами, как Doxygen). Только не путайте эту документацию, предназначенную для пользователей, с той, которая будет полезна для сопровождающих библиотеку.
прокомментируйте, что не может быть в коде, например, требования политики, которые объясняют, почему все так, как есть.
комментируйте справочную информацию, такую как ссылка на научную статью, которая описывает умный алгоритм, который вы используете, или RFC, стандартизирующий сетевой протокол, который вы реализуете.
комментируйте хаки! Каждый иногда вынужден использовать хаки или обходные пути, но будьте добры к будущему сопровождающему, прокомментируйте это. Читайте " Технический долг".
И не комментируйте остальное. Количественные правила, такие как "20 % строк должны быть комментариями", явно глупы и явно предназначены только для PHB.
Нет хороших правил с точки зрения соотношения комментариев / кода. Это полностью зависит от сложности вашего кода.
Я придерживаюсь одного (и только одного) правила в отношении комментариев (мне нравится оставаться гибким).
Код показывает, как все сделано, комментарии показывают, что сделано.
Некоторый код вообще не нуждается в комментариях из-за своей очевидности: это часто может быть достигнуто путем использования хороших имен переменных. В основном я буду комментировать функцию, а затем комментировать основные блоки с помощью этой функции.
Я считаю это плохим
// Process list by running through the whole list,
// processing each node within the list.
//
void processList (tNode *s) {
while (s != NULL) { // Run until reached end of list.
processNode (s); // Process the node.
s = s->nxt; // Move to next node.
}
}
так как все, что вы там делаете, это трижды пишете код. Я бы предпочел что-то вроде:
// Process list (or rest of list if you pass a non-start node).
//
void processList (tNode *currentNode) {
// Run through the list, processing each node.
while (currentNode != NULL) {
processNode (currentNode);
currentNode = currentNode->nextNode;
}
}
Я не был бы настолько груб, чтобы сказать, что комментарии оправдывают плохо запрограммированный код, как некоторые люди выше, и не говорят, что они вам не нужны.
Это также зависит от вашего редактора и того, как вы хотели бы видеть в нем свой код, и как бы вы хотели, чтобы другие делали это.
Например, мне нравится создавать регионы в C#. Области называются сворачиваемыми областями кода, в некотором роде закомментированными контейнерами кода. Таким образом, когда я смотрю на редактор, я на самом деле смотрю на псевдокод.
#region Connect to the database
// ....
#endregion
#region Prepare tables
#region Cache tables ...
#endregion
#region Fix column names ...
#endregion
#endregion
Этот вид кода более читабелен, чем все остальное, что я знаю, кроме, конечно, он нуждается в редакторе, поддерживающем пользовательское свертывание с именами. (как редактор Visual Studio, VIM...). Кто-то скажет, что вы можете добиться аналогичного результата, если поместите регионы в процедуры, но, во-первых, вы не всегда можете сделать это, во-вторых, вам нужно перейти к процедуре, чтобы увидеть ее код. Если вы просто установили горячие клавиши, чтобы открывать / сворачивать регион, вы можете быстро увидеть код в нем при прокрутке и чтении текста и, как правило, быстро перемещаться по иерархии регионов.
Что касается строковых комментариев, было бы хорошо написать код, который автоматически самодокументируется, но, к сожалению, этого нельзя сказать в целом. Этот курс зависит от проектов, его области и сложности.
В качестве последнего замечания я полностью предлагаю документацию в коде с помощью переносимого и независимого от языка инструмента, например, NaturalDocs, который можно настроить для работы с любым языком с естественным синтаксисом, который не включает XML, или каким-либо другим специальным форматированием (следовательно, имя) плюс его не нужно устанавливать более одного раза.
И если есть парень, которому не нравятся комментарии, он всегда может удалить их, используя какой-то простой инструмент. Я даже интегрировал такой инструмент в свой редактор, и комментарии пропускались простым щелчком меню. Таким образом, комментарии не могут повредить код в любом случае, который не может быть исправлен очень быстро.
Вы, ребята, можете спорить, но я действительно верю в это:
Обычно вам не нужно писать комментарии. Просто так. Код должен быть написан таким образом, чтобы он сам объяснял, если он не объясняет себя, и вы должны писать комментарии, значит что-то не так.
Однако есть несколько исключительных случаев:
- Вы должны написать что-то очень ОЧЕНЬ загадочное, чтобы добиться успеха. Поэтому здесь вам может понадобиться написать какое-то объяснение.
- Вы предоставляете библиотеку какой-то другой группе / компании, лучше документируйте ее API.
- В вашей организации слишком много начинающих программистов.
Нет метрик, которые вы могли бы разумно использовать для комментариев. Никогда не говорите, что у x строк кода должно быть y комментариев, потому что тогда вы получите глупые бесполезные комментарии, которые просто повторяют код, и это ухудшит качество вашего кода.
100 строк кода должны иметь как можно меньше комментариев.
Лично, используя их в прошлом, я не стал бы использовать такие вещи, как doxygen, для документирования внутреннего кода в объеме каждой функции и каждого параметра, требующего тегового описания, потому что с хорошо продуманным кодом у вас много функций и с хорошими именами, чаще всего это описания тегов не говорят ничего больше, чем само имя параметра.
Я говорю, что обычно комментарии - это неприятный запах. Но документация по встроенному коду великолепна. Я более подробно рассказал об этом на http://robowiki.net/:
Я не знаю ни одного инструмента, но я чувствую, что всегда хорошо иметь некоторые комментарии в коде, если он будет поддерживаться кем-то другим в будущем. По крайней мере, хорошо иметь блоки заголовков для классов и методов, подробно описывающих, для чего предназначен класс и что делает метод. Но да, хорошо, чтобы комментарии были минимальными.
Я предпочитаю использовать комментарии, чтобы объяснить
- что должен делать класс \ функция,
- что это не должно делать,
- любые предположения, которые я делаю, что пользователи класса \ функции должны придерживаться.
Для пользователей редактора vi следующий плагин очень полезен. Мы можем определить шаблоны для комментариев класса, комментариев к функциям и т. Д.
Я согласен со всеми в отношении самодокументируемого кода. И я также согласен с необходимостью специальных комментариев, когда дело доходит до генерации документации. Краткий комментарий в верхней части каждого метода / класса полезен, особенно если ваша IDE может использовать его для всплывающих подсказок при завершении кода (например, Visual Studio).
Другая причина комментариев, о которых я не упомянул, это небезопасные языки, такие как JavaScript или PHP. Вы можете указать типы данных таким образом, хотя венгерская нотация также может помочь в этом (я думаю, это один из редких случаев правильного использования).
Кроме того, такие инструменты, как PHPLint, могут использовать специальные комментарии, связанные с типами, для проверки вашего кода на предмет безопасности типов.
Исходный код всегда должен быть документирован, где это необходимо. Люди спорили о том, что и что нельзя документировать. Однако я хотел приписать еще одну заметку.
Допустим, я реализовал метод, который возвращает а / б
Так как я программист, я великий гражданин, и я намекаю пользователю, чего ожидать.
/**
* Will return 0 if b is 0, to prevent the world from exploding.
*/
float divide(float a, float b) {
if (b == 0) return 0;
return a/b;
}
Я знаю, это довольно очевидно, что никто никогда не будет создавать такой метод. Но это может быть отражено и в других вопросах, когда пользователи API не могут понять, чего ожидает функция.
Мое мнение - комментарии в исходном коде это зло. Код должен быть самодокументирован. Разработчики обычно забывают о прочтении и обновлении их.
Как грустит Мартин Фаулер: "если вам нужен комментарий для блока строк - просто сделайте новую функцию" (это не цитата - эта фраза, как я ее помню).
Будет лучше сохранить отдельную документацию для служебных модулей, основные принципы вашего проекта, организацию библиотек, некоторые алгоритмы и идеи дизайна.
Почти забыли: я использовал комментарии кода один раз. Это был MFC/COM -проект, и я оставляю ссылки из статей MSDN с практическими рекомендациями рядом с нетривиальными решениями / обходными решениями.
100 строк исходного кода - должно быть понятно, если нет - его следует разделить или реорганизовать на несколько функций - что будет более понятно.
Есть ли инструмент для создания каркаса для комментариев на платформе Unix для C++?
В Vim есть плагины для вставки шаблона комментариев doxygen, если вам это действительно нужно.