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

Question

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

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

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

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

Answer 1

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

Answer 2

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

В общем, если ваше исправление ошибки теперь заставляет код работать ПРАВИЛЬНО, просто оставьте его без комментариев. Не нужно комментировать правильный код.

Иногда исправление ошибки делает вещи странными, или исправление ошибки проверяет что-то необычное. Тогда может быть уместно иметь комментарий - обычно комментарий должен ссылаться на «номер ошибки» из вашей базы данных ошибок. Например, у вас может быть комментарий, который гласит: «Ошибка 123 - учет нечетного поведения, когда пользователь имеет разрешение экрана 640 на 480».

Answer 3

Если код исправлен, комментарий бесполезен и никогда никому не интересен - только шум.

Если ошибка не устранена, комментарий неверный. Тогда это имеет смысл. :) Так что просто оставляйте такие комментарии, если вы действительно не решили ошибку.

Answer 4

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

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

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

Только мои два цента.

Answer 5

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

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

Answer 6

Не дублируйте метаданные, которые ваша VCS будет хранить для вас. Даты и имена должны быть автоматически добавлены VCS. Номера билетов, имена менеджеров / пользователей, которые запросили изменение, и т. Д. Должны быть в комментариях VCS, а не в коде.

Вместо этого:

// БИЛЕТ $ DATE $ NAME $ // полезный комментарий к следующей бедной душе

Я бы сделал это:

// полезный комментарий к следующей бедной душе

Answer 7

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

Большую часть времени я добавляю в код специальные замечания, подобные этой:

// I KNOW this may look strange to you, but I have to use
// this special implementation here - if you don't understand that,
// maybe you are the wrong person for the job.

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

Answer 8

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

Помните, что ошибок нет, просто недостаточно тестирования.

Answer 9

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

В своем собственном коде я редко комментирую исправления ошибок.

Answer 10

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

В противном случае сообщение, которое вы вводите при регистрации, не должно содержать всю необходимую информацию.

ура

Rob