Это в порядке для помещения комментариев об исправлениях ошибок в исходном коде?

Добавление комментария об исправлении ошибок - хорошая идея, если вы пишете правильно.

Например,

/* I know this looks wrong, but originally foo was being decremented here, and 
   it caused the baz to sproing. Remember, the logic is negated by blort! */

Наподобие Исправляет ошибку №22 лучше хранить в системе контроля версий. Комментарии в вашем коде должны быть указателями, чтобы помочь будущим путешественникам на их пути, а не удовлетворять процесс и отслеживание.

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

Моя причина в том, что это ремонтопригодность - 2 (или 10) лет спустя этот комментарий не будет больше иметь смысл. В приведенном выше примере я бы предпочел что-то вроде:

// Increment i to counteract extra decrement
++i;

Разница в том, что это не связано с ошибкой , а скорее с тем, что делает код. Комментарии должны комментировать код, а не метаинформацию, ИМО.

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

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

У нас было несколько подобных комментариев, но затем наш сервер Bugzilla умер, и мы перезапустились с ошибкой №1, поэтому все они бессмысленны. Сейчас я предпочитаю краткое объяснение ошибки.

Что-то вроде // исправляет ошибку №22 само по себе совершенно бессмысленно и требует дополнительных шагов, чтобы даже понять, что он означает и какую роль выполняет. Краткое описание, на мой взгляд, более уместно, независимо от того, какое программное обеспечение для отслеживания ошибок или контроля версий вы используете.

Если алгоритм необходимо закодировать определенным образом - например, для обхода ошибки в стороннем API, то это следует прокомментировать в коде, чтобы следующий человек, который придет не пытается «оптимизировать» код (или что-то еще) и повторно ввести проблему.

Если это связано с добавлением комментария при исправлении исходной ошибки, сделайте это.

Он также будет служить маркером, чтобы вы можете найти код, который вам нужен, чтобы проверить, когда вы когда-нибудь обновитесь до следующей версии API.

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

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

Предполагая, что комментарии не лишние (классический i ++; // инкремент i ), почти никогда не бывает причин возражать против добавления комментария, независимо от того, с чем он связан. Информация полезная. Однако лучше быть описательным и кратким - не говорите «исправляет ошибку №YY», но вместо этого добавьте что-то вроде «это использовалось для сбоя при x = 0, дополнительная логика здесь предотвращает это». Таким образом, кто-то, кто посмотрит код позже, сможет понять, почему конкретный раздел важен для правильного функционирования.

Я считаю, что комментарии должны соответствовать намерениям разработчика или подчеркивать «почему», окружающее алгоритм / метод.

Комментарии не должны окружать временное исправление.

I согласны с тем, что такие данные должны быть помещены в систему контроля версий или другую часть Управления конфигурациями. Поработав с кодовыми базами, которые помещают информацию об исправлениях ошибок в комментарии, я могу сказать, что позже это приводит к очень загроможденным комментариям и коду. Через шесть месяцев после установки исправления вы действительно хотите знать это о строке, исправляющей какую-то давно прошедшую ошибку? Что вы делаете с комментариями, когда вам нужно реорганизовать код?

Мы используем Team Foundation Server для управления версиями здесь, в моей компании, и он позволяет вам связать регистрацию с отчетом об ошибке, поэтому я не буду помещать комментарий непосредственно в код для сервера та же цель.

Однако , в ситуациях, когда я использую код в качестве обходного пути для ошибки в платформе .NET или сторонней библиотеке, мне нравится помещать URL-адрес в журнал или веб-сайт Microsoft TechNet с описанием ошибки и ее статуса.

In the Perl5 source repository it is common to refer to bugs, with their associated Trac number in Test files.

This makes more sense to me, because adding a test for a bug will prevent that bug from ever going unnoticed again.

So obviously

    // fix bug #22
    i++;

is not effective communication.

Good communication is mostly common sense. Say what you mean.

    // Compensate for removeFrob() decrementing i.
    i++;

Include the bug number if it seems likely to help future readers.

    // Skipping the next flange is necessary to maintain the loop
    // invariant if the lookup fails (bug #22).
    i++;

Sometimes important conversations are recorded in your bug tracking system. Sometimes a bug leads to a key insight that changes the shape of the code.

    // Treat this as a bleet. Misnomed grotzjammers and particle
    // bleets are actually both special cases of the same
    // situation; see Anna's analysis in bug #22.
    i++;