Некоторые из моих коллег используют специальные комментарии по исправлениям ошибок, например:
// 2008-09-23 John Doe - bug 12345
// <short description>
Это имеет смысл?
Вы комментируете исправления ошибок особым образом?
Пожалуйста, дайте мне знать.
Я не комментирую такие комментарии, система управления версиями уже поддерживает эту историю, и я уже могу зарегистрировать историю файла.
Я делаю комментарии, которые описывают, почему что-то неочевидное делается, хотя. Поэтому, если исправление ошибки делает код менее предсказуемым и понятным, я объясню, почему.
Со временем они могут накапливаться и добавлять беспорядок. Лучше сделать код понятным, добавить любые комментарии к связанным ошибкам, которые могут быть не очевидны, и сохранить деталь ошибки в системе отслеживания и хранилище.
Я стараюсь не комментировать фактический источник, потому что это может быть трудно поддерживать в актуальном состоянии. Однако я помещаю ссылку на комментарии в свой журнал управления версиями и выдает трекер. например Я могу сделать что-то подобное в Perforce:
[Ошибка-Id] Проблема с диалогом xyz. Перемещенный код для выбора в abc и теперь инициализировать позже.
Тогда в моей проблеме трекер я сделаю что-то вроде:
Исправлено в списке изменений 1234.
Перемещенный код прокрутки в abc и теперь инициализировать позже.
Потому что тогда остается хороший исторический маркер. Также упрощается, если вы хотите знать, почему определенная строка кода является определенным способом, вы можете просто просмотреть историю файлов. После того, как вы нашли строку кода, вы можете прочитать мой комментарий коммита и четко увидеть, какая ошибка была и как я ее исправил.
Только если решение было особенно умно или трудно понять.
Я обычно добавляю свое имя, свой адрес электронной почты и дату вместе с кратким описанием того, что я изменил. Это потому, что в качестве консультанта я часто фиксирую код других людей.
// Glenn F. Henriksen (<[email protected]) - 2008-09-23
// <Short description>
Таким образом, владельцы кода или люди, пришедшие после меня, могут выяснить, что произошло, и они могут связаться со мной, если они должны.
(да, к сожалению, чаще всего у них нет контроля источника... для внутренних вещей я использую отслеживание TFS)
Хотя это может показаться хорошей идеей в то время, она быстро выходит из-под контроля. Такая информация может быть лучше захвачена с использованием хорошей комбинации системы управления версиями и отслеживания ошибок. Конечно, если есть что-то сложное, комментарий, описывающий ситуацию, будет полезен в любом случае, но не дата, имя или номер ошибки.
Кодовая база, над которой я сейчас работаю, - это что-то вроде 20 лет, и они, похоже, добавили много комментариев, подобных этому годам назад. К счастью, они прекратили делать это через несколько лет после того, как в конце 90-х годов они превратили все в CVS. Тем не менее, такие комментарии по-прежнему усеяны по всему коду, и теперь политика "удаляет их, если вы работаете непосредственно над этим кодом, но в противном случае оставляете их". Их часто очень сложно отслеживать, особенно если один и тот же код добавлен и удален несколько раз (да, бывает). Они также не содержат дату, но содержат номер ошибки, который вам нужно будет искать в архаичной системе, чтобы найти дату, поэтому никто не делает.
Комментарии, подобные этому, - это то, почему Subversion позволяет вводить запись в журнале при каждой фиксации. То, где вы должны поместить этот материал, а не в код.
В то время как я обычно вижу некоторые комментарии к ошибкам внутри кода на работе, мои личные предпочтения связывают фиксацию кода с одной ошибкой. Когда я говорю одно, я действительно имею в виду одну ошибку. Впоследствии вы всегда можете посмотреть сделанные изменения и узнать, к какой ошибке они были применены.
Я делаю это, если исправление ошибки включает в себя что-то не простое, но чаще всего, если для исправления требуется длинное объяснение, я воспринимаю его как знак того, что исправление не было хорошо спроектировано. Иногда мне приходится работать с открытым интерфейсом, который не может измениться, поэтому он, как правило, является источником таких комментариев, например:
// <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.
В других случаях сообщение фиксации управления источником - это то, что я использую, чтобы аннотировать изменение.
Этот стиль комментариев чрезвычайно ценен в среде с несколькими разработчиками, где у разработчиков есть множество навыков и/или знаний о бизнесе (например, везде).
Для опытного знающего разработчика причина изменения может быть очевидной, но для более новых разработчиков этот комментарий заставит их подумать дважды и сделать больше исследований, прежде чем возиться с ним. Это также помогает им узнать больше о том, как работает система.
О, и примечание из опыта о том, что "я просто положил это в систему управления версиями":
Если это не в источнике, этого не произошло.
Я не могу подсчитать, сколько раз исходная история для проектов была потеряна из-за неопытности с программным обеспечением управления версиями, неправильной моделью ветвления и т.д. Существует только одно место история изменений не может быть потеряна - и это в исходном файле.
Обычно я помещаю его туда, а затем вырезаю 'n вставляем один и тот же комментарий, когда я его проверяю.
Нет, я этого не делаю, и я ненавижу граффити, как этот мусор кода. Номера ошибок можно отследить в сообщении фиксации системе управления версиями и по сценариям, чтобы направить соответствующие сообщения фиксации в систему отслеживания ошибок. Я не верю, что они принадлежат к исходному коду, где будущие изменения будут просто путать вещи.
Часто такой комментарий более сбивает с толку, так как у вас действительно нет контекста относительно того, как выглядел оригинальный код, или из-за неправильного поведения.
В общем, если исправление ошибки теперь заставляет код работать ПРАВИЛЬНО, просто оставьте его без комментариев. Нет необходимости комментировать правильный код.
Иногда исправление ошибок делает вещи странными, или исправление ошибок тестирует что-то необычное. Тогда, возможно, было бы целесообразно иметь комментарий - обычно комментарий должен ссылаться на "номер ошибки" из вашей базы данных ошибок. Например, у вас может быть комментарий, в котором говорится: "Ошибка 123 - учетная запись для нечетного поведения, когда пользователь находится в разрешении экрана 640 на 480".
Если вы добавите такие комментарии после нескольких лет поддержки кода, у вас будет так много исправленных ошибок, вы не сможете прочитать код.
Но если вы измените что-то, что выглядит правильно (но с тонкой ошибкой) во что-то более сложное, приятно добавить короткий комментарий, объясняющий, что вы сделали, чтобы следующий программист поддерживал этот код, не менял его потому что он (или она) думает, что вы слишком усложнили ситуацию по уважительной причине.
Нет. Я использую subversion и всегда вводю описание моей мотивации для совершения изменения. Я обычно не повторяю решение на английском языке, вместо этого я суммирую сделанные изменения.
Я работал над несколькими проектами, где они добавляли комментарии в код, когда были исправлены ошибки. Интересно, и, вероятно, не случайно, это были проекты, которые либо не использовали какой-либо инструмент управления источниками, либо им было поручено следовать этому соглашению по соглашению руководства.
Честно говоря, я действительно не вижу значения в этом для большинства ситуаций. Если я хочу знать, что изменилось, я рассмотрю журнал subversion и diff.
Только мои два цента.
Если код исправлен, комментарий бесполезен и никому не интересен - просто шум.
Если ошибка не решена, комментарий неверен. Тогда это имеет смысл.:) Так что просто оставляйте такие комментарии, если вы действительно не решили ошибку.
Чтобы найти конкретный комментарий, мы используем DKBUGBUG, что означает, что исправление и рецензент Дэвида Келли может легко идентифицировать себя. Конечно, мы добавим дату и другой номер отслеживания ошибок VSTS и т.д. вместе с этим.
Не дублируйте метаданные, которые ваш VCS будет хранить для вас. Даты и имена должны быть автоматически добавлены VCS. Номера билетов, имена менеджеров/пользователей, которые запросили изменение, и т.д. Должны быть в комментариях VCS, а не в коде.
Вместо этого:
//$DATE $NAME $БИЛЕТ // полезный комментарий следующей бедной душе
Я бы сделал это:
//полезный комментарий следующей бедной душе
Если код находится на живой платформе, вдали от прямого доступа к репозиторию управления версиями, я добавлю комментарии, чтобы выделить изменения, сделанные как часть исправления для ошибки в живой системе.
В противном случае сообщение, которое вы вводите при регистрации, должно содержать всю необходимую информацию.
веселит,
Rob
Когда я делаю исправления/улучшения в сторонних библиотеках/компонентах, я часто делаю некоторые комментарии. Это облегчает поиск и перемещение изменений, если мне нужно использовать более новую версию библиотеки/компонента.
В моем собственном коде я редко комментирую исправления.
Я не работаю над проектами с несколькими людьми, но иногда добавляю комментарии об определенной ошибке в unit test.
Помните, что таких ошибок нет, просто недостаточно тестирования.
Так как я делаю как можно больше 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.
Звучит жестоко, но большинство людей, которые называют себя "разработчиками", не заслуживают других замечаний.