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


16

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

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

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

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

33

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

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


4

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


3

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


15

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

  0

Вы совершенно правы. Я помню один метод в нашем коде, который, как представляется, состоит только из исправлений ошибок (в отношении комментариев, упомянутых выше)! 23 сен. 082008-09-23 21:23:31

  0

Что такое репозиторий системы отслеживания? 27 сен. 112011-09-27 16:15:32

  0

Когда я упомянул «систему слежения и хранилище», я имел в виду две вещи. Одна, система отслеживания ошибок, например bugzilla или JIRA, где вы можете размещать комментарии о проблеме. Во-вторых, репозиторий исходного кода, такой как SVN или Git, где вы можете добавлять комментарии с фиксациями. 29 сен. 112011-09-29 19:40:22


2

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


0

Чтобы найти тот, конкретный комментарий, мы используем DKBUGBUG - это значит, исправить и рецензент Дэвида Келли могут легко идентичность, Ofcourse мы добавим дату и другие VS ошибка номера отслеживания и т.д. наряду с этим.


6

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

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

Тогда в моем отслеживания ошибок я буду делать что-то вроде:

Фиксированный в 1234.

список изменений

Переехал проклейки код АВС и теперь Initialise позже.

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


4

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

// Glenn F. Henriksen (<[email protected]) - 2008-09-23 
// <Short description> 

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

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

+2

Sourcecontrol отслеживает всю эту информацию. И, поскольку вы консультант, вы должны проконсультироваться с вашим клиентом, чтобы использовать систему управления версиями. 02 фев. 112011-02-02 08:13:01

+1

Я проконсультируюсь, но иногда мой совет падает на глухие уши. Если у клиента есть контроль источника, я никогда не помещал эти комментарии, тогда это просто дополнительный шум. 05 апр. 112011-04-05 19:46:22

  0

Что такое система управления версиями? 27 сен. 112011-09-27 16:16:40

  0

@MarkKramer Зависит от клиента. Microsoft Team Foundation является наиболее распространенным. Git также используется немного. Время от времени я натыкаюсь на Visual SourceSafe ... 10 окт. 112011-10-10 13:16:19


1

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


4

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

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


0

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

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

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

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

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


2

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

// <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. 

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


1

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

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

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


2

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

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

О, и записка от опыта о «Я просто положить, что в системе управления источником» комментарии:

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

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

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

+1

Не согласен здесь. Что происходит, когда вы реорганизуете этот метод? Имеет смысл также удалить комментарий. 24 сен. 082008-09-24 21:40:24

+1

Конечно, удаление старого кода и связанных с ним комментариев в порядке. Это часть того, что вы только оставляете свои комментарии во внешней системе, которая может потерять их для вас, пока они все еще действительны, с которыми я не согласен. :-) 24 сен. 082008-09-24 22:05:38

  0

Резервное копирование. Резервное копирование. Резервное копирование? 14 июл. 102010-07-14 17:12:48

+1

Резервные копии не могут исправить глупость. См. Параграф о неопытности и неправильных моделях ветвления. 14 июл. 102010-07-14 19:59:16


1

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

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


0

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

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

веселит,

Роб


1

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

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

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

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


0

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

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


0

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

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


0

Поскольку я делаю как можно больше 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. 

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


1

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

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