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

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

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

 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

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

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

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

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

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

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

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

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

Нет.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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