Используете ли вы специальные комментарии по исправлению ошибок в вашем коде?

Question

Некоторые из моих коллег используют специальные комментарии по своим исправлениям ошибок, например:

// 2008-09-23 John Doe - bug 12345
// <short description>

Имеет ли это смысл?
Вы комментируете исправления ошибок особым образом?

Пожалуйста, дайте мне знать.

Answer 1

Я не добавляю подобные комментарии, система контроля версий уже поддерживает эту историю, и я уже могу вести историю файла.

Я помещаю комментарии, которые описывают, почему делается что-то неочевидное. Поэтому, если исправление ошибки делает код менее предсказуемым и понятным, я объясню почему.

Answer 2

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

Answer 3

Я склонен не комментировать в фактическом источнике, потому что это может быть трудно поддерживать в курсе. Тем не менее, я размещаю комментарии в своем журнале контроля версий и трекере ошибок. например Я мог бы сделать что-то подобное в Perforce:

[Bug-Id] Проблема с диалоговым окном xyz. Код изменения размеров перенесен в abc и теперь инициализировать позже.

Тогда в моем трекере выпусков я сделаю что-то вроде:

Исправлено в списке изменений 1234.

Перемещен размерный код в abc и теперь инициализировать позже.

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

Answer 4

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

Кодовая база, над которой я сейчас работаю, составляет около 20 лет, и они, похоже, добавили много комментариев, как это было много лет назад. К счастью, они прекратили это делать через несколько лет после того, как в конце 90-х они перевели все на CVS. Однако такие комментарии все еще замусорены в коде, и теперь политика гласит: «Удалите их, если вы работаете непосредственно с этим кодом, но в противном случае оставьте их». За ними часто очень трудно следовать, особенно если один и тот же код добавляется и удаляется несколько раз (да, это происходит). Они также не содержат дату, но содержат номер ошибки, который вам нужно найти в архаичной системе, чтобы найти дату, так что никто этого не делает.

Answer 5

Я обычно добавляю свое имя, адрес электронной почты и дату вместе с кратким описанием того, что я изменил, потому что, как консультант, я часто исправляю код других людей.

// Glenn F. Henriksen (<email@company.no) - 2008-09-23
// <Short description>

Таким образом, владельцы кода или люди, приходящие за мной, могут выяснить, что произошло, и они могут связаться со мной, если потребуется.

(да, к сожалению, чаще всего они не имеют контроля исходного кода ... для внутренних вещей я использую отслеживание TFS)

Answer 6

Только если решение было особенно умным или трудным для понимания.

Answer 7

В комментариях, подобных этому, Subversion позволяет вам вводить записи в журнале при каждом коммите. Вот где вы должны поместить этот материал, а не в код.

Answer 8

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

// <date> [my name] - Bug xxxxx happens when the foo parameter is null, but
// some customers want the behavior.  Jump through some hoops to find a default value.

В других случаях сообщение коммита управления исходным кодом - это то, что я использую, чтобы аннотировать изменение.

Answer 9

Такой стиль комментирования чрезвычайно ценен в среде с несколькими разработчиками, где у разработчиков имеется целый ряд навыков и / или бизнес-знаний (например, везде).

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

Да, и заметка из опыта о комментариях "Я просто поместил это в систему контроля версий":

Если его нет в источнике, этого не произошло.

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

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

Answer 10

В то время как я действительно вижу некоторые комментарии к ошибкам внутри кода на работе, мое личное предпочтение - связать коммит кода с одной ошибкой. Когда я говорю один, я действительно имею в виду одну ошибку. После этого вы всегда можете посмотреть на сделанные изменения и узнать, к какой ошибке они были применены.