Хорошая идея поместить номера ошибок в комментарии в начале исходного файла? [закрыто]

40

Является ли хорошей практикой помещать номера ошибок в самом файле внутри заголовка комментария?

Комментарии будут выглядеть примерно так:

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

Это кажется полезным, но считается ли это плохой практикой?

Geek
источник
23
Вопрос, который я задам: «Что вы можете сделать со встроенными номерами ошибок, которые вы уже не можете сделать с базой данных ошибок?» Я не могу думать ни о каких реальных случаях использования.
М. Дадли
2
Связанный: stackoverflow.com/questions/123936/…
Брайан,
6
@JensG Вот почему вы помещаете это в сообщение коммита, а значок logв файле даст вам почти то же самое, но без загромождения файла ...
Izkata
1
@JensG А когда вы исправили десятки или сотни дефектов в конкретном файле? Очевидный ответ заключается в том, что вы периодически очищаете устаревшие идентификаторы, но затем вы возвращаетесь к просмотру журнала VC ...
dmckee
3
Этот вопрос является предметом статьи Ars Technica. Должны ли мы перечислять ошибки в заголовке исходного файла? (опубликовано через 15 дней после публикации этого вопроса).
Питер Мортенсен

Ответы:

107

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

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

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

Томас Оуэнс
источник
2
«И если вы используете современную систему контроля версий, которая поддерживает наборы изменений, то она фактически теряет информацию об изменениях». - не могли бы вы уточнить, пожалуйста?
Компьютерщик
10
@ Не знаю, что объяснить. Если вы посмотрите на файл, который ссылается на идентификационный номер ошибки, вы не увидите изменений в других файлах в результате того же дефекта, если не выполните поиск файлов. Вот что такое набор изменений - набор файлов, зарегистрированных вместе.
Томас Оуэнс
9
Я бы также добавил, что если вы перейдете на новую систему отслеживания ошибок, все эти цифры мгновенно станут бесполезными. Я столкнулся с этим на моей нынешней работе, где в некоторых комментариях есть цифры от программного обеспечения для отслеживания ошибок, которое не использовалось в течение 10 лет.
17 из 26
2
Поэтому после перехода на новую систему отслеживания ошибок они становятся такими же полезными, как если бы их никогда не было. Но если предположить, что они предоставили некоторую ценность в какой-то момент и не дают отрицательной ценности сейчас, почему бы не сделать это?
Cruncher
@ 17of26 - Я полагаю, что вы могли бы связать старые ошибки / проблемы с новыми, если бы не было другого механизма, кроме как комментарий типа «старая ошибка отслеживания ошибок 1234».
Кенни Эвитт
42

Есть только один случай, когда я бы сделал это, а именно как часть предупреждения для будущих программистов: «Не вызывайте foo()здесь функцию напрямую; это вызвало ошибку # 1234, а именно ...», а затем краткое описание ошибка следует.

И если код изменился таким образом, что нет соблазна вызвать foo()напрямую, удалите этот комментарий. Это только раздражало и взрывало код.

рем
источник
19
Может быть, я немного задира, но если foo()не вызывать напрямую, то код должен быть структурирован таким образом, чтобы этого не могло быть.
MetaFight
20
О, я пытался написать что-то в качестве примера, чтобы сделать текст более конкретным - не воспринимайте меня слишком буквально. В лучшем случае был бы случай, когда вы использовали внешнюю библиотеку, и функция, которую вы обычно использовали для определенной цели, имела ошибку. Тогда комментарий «Не звоните foo()сюда» будет разумным.
бэр
16

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

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

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

Нет.

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

Нил Барнвелл
источник
2
это была своего рода система управления версиями (и я видел, что она использовалась оперативно в домах программного обеспечения еще в 2006 году, и, без сомнения, где-то сегодня используется).
jwenting
1
@jwenting Я видел вопросы на этом самом сайте от людей, достаточно несчастных, чтобы в настоящее время работать в магазинах, где это является текущей практикой :-(
Carson63000
Мы используем отличную систему контроля версий. Никто, кроме меня, не добавляет комментарии при проверке кода. <shrug> Я комментирую определенные вещи (например, PLSQL, который не всегда отслеживается SCM). Я комментирую свой код, чтобы объяснить, но никогда не привязываю его к конкретным ошибкам, но я всегда ссылаюсь на ошибки в комментариях к коммитам SCM, когда регистрируюсь. Надеюсь, в конце концов кто-то это оценит.
Pedantic
11

Это, ИМХО, очень плохая идея. После редакции № 100 у вас будет 90% комментариев и 10% кода. Я не считаю это чистым и читабельным.

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

Док Браун
источник
8

Я вижу, что все противостоят этой идее и дали историческую причину (эпоха контроля перед источником), почему люди это делали.

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

Да, это загромождает код, но помогает найти причину, почему этот кусок кода есть.

Parvez
источник
3
Абсолютно. Иногда у меня возникает небольшое чувство, что программисты приходят в ужас от избыточности, поэтому они избегают доступа к одной и той же информации разными способами. Это очень интересно, потому что программисты, как правило, также ужасаются плохой производительностью и поэтому используют кеши в своих программах. Но кэширование номеров ошибок в коде рядом с местом, где они наиболее полезны, считается плохим? Мммм.
JensG
Часто есть другой способ получить эту информацию (в проекте, над которым я работаю, было бы right click > Team > Show Annotationsобвинение в текущем файле), но разница в том, что с комментариями есть возможность обнаружения - они могут выпасть на вас - и с аннотациями вы должны сознательно решить искать их.
Дэвид Конрад
Думай, решай, кликай, кликай, кликай, прокручивай. Вот почему я сказал «кеширование в коде». Если это там, я просто вижу это.
JensG
2
@JensG Интересная точка зрения. Кэши могут улучшить производительность, но они также имеют стоимость переноса. Если кэш должен быть заполнен, обновлен, аннулирован, очищен и т. Д. Излишними человеческими усилиями, я бы поставил под сомнение соотношение затрат и выгод, особенно учитывая, насколько ужасны люди в синхронизации таких денормализованных конструкций.
Джеффри Хантин
7

Одним из пунктов в тесте Джоэла является

У вас есть база данных ошибок?

Такая информация может храниться в базе данных ошибок, если вы думаете, что они важны, но они будут только шумом в комментариях.

Пьер Арло
источник
1
См. Пример в вопросе - комментарии будут ссылаться на базу данных об ошибках ...
Izkata
@Izkata Но в этом все дело. Сама база данных может иметь поле «комментарий» с комментарием. Вопрос не в том, есть база данных ошибок или нет, а в том, стоит ли хранить ее в исходном файле. Я думаю, даже если они являются комментариями, они должны храниться в самой базе данных, потому что это то, для чего это нужно.
Пьер Арло,
6

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

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

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

Связанное с этим отслеживание ошибок и функций, а также причина, по которой вы изменяете этот файл, могут дать вам представление о том, насколько глубоко вам нужно копаться в истории и, возможно, просматривать различия. У меня была просьба «Вернуться к исходной формуле». Я знал, куда идти в истории изменений, и просматривал только один или два сравнения.

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

JeffO
источник
2

Если у вас нет VCS с сообщениями о фиксации, и нет системы отслеживания ошибок с возможностью оставлять комментарии, это один из вариантов, а не оптимальный, для отслеживания изменений.
Лучше иметь электронную таблицу с этой информацией, или, если вы находитесь в среде без такой «роскоши», текстовый файл, расположенный где-то рядом с вашими источниками.
Но я настоятельно рекомендую, если вы находитесь в такой среде, чтобы начать строить дело к инвестированию в VCS и систему отслеживания ошибок :)

jwenting
источник
2

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

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

Лично я думаю, что есть место как для инструментов, так и для записи кода.

GGB
источник
2

Я знаю , что Git не делает это и простой ответ «зачем бы он туда?»

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

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

djechlin
источник
2

Нет, не рекомендуется отслеживать исправления ошибок в виде комментариев в коде. Это только создает беспорядок.

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

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

Если вы ищете хорошее чтение на эту тему, я рекомендую четвертую главу Чистого кода .

Брайан
источник
Уведомления об авторских правах также присутствуют (слегка излишне), чтобы уведомить сотрудников о том, что файл принадлежит работодателю. И , возможно , отпугивает незаконного обмена (даже со стороны сотрудников), судя по тому, как многие люди считают , что авторское право распространяется только если это уведомление.
Бернд Джендриссек
1

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

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

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

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

StingyJack
источник
3
вопрос касается комментариев в начале исходного файла, сразу после сообщения об авторских правах - это не имеет ничего общего с комментариями в более узких областях
gnat
Все ответы здесь говорят только об этом, хотя. Если я внесу значительные изменения во весь файл класса (реорганизация или исправление форматирования), я не прокомментирую файл класса как область видимости?
StingyJack
0

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

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

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

Фьяметта Кастальди
источник
0

Я определенно не помещал бы такую ​​информацию в начало файла - обычно такая вещь принадлежит системе тикетов.

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

hstoerr
источник
это, кажется, не добавляет существенной ценности к тому, что уже было опубликовано в предыдущих ответах
gnat
0

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

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

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

Фред Томсен
источник