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

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

// added for superEnterpriseyWonder v2.5
string superMappingTag = MakeTag(extras);
if (superMappingTag.empty())
{
     autoMapping = false;
}
// end added for superEnterpriseyWonder v2.5

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

ОТВЕТЫ

Ответ 1

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

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

// added for superEnterpriseyWonder v2.5
string superMappingTag = MakeTag(extras);
if (superMappingTag.empty())
{
     // bug fix #12345674 shuld have been true
     autoMapping = true;
     // bug fix #12345674 should have been true
     i++; // v2.6 now need to up the counter DO NOT DELETE
}
// end added for superEnterpriseyWonder v2.5

а затем кто-то удалит этот метод, но оставит комментарий кода в

// added for superEnterpriseyWonder v2.5
     // bug fix #12345674 should have been true
     // v2.6 now need to up the counter DO NOT DELETE
// end added for superEnterpriseyWonder v2.5

Просто скажи "нет" дерьмовым комментариям

Ответ 2

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

Это из чистого кода, книга Боба Мартина:

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

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

Ответ 3

Я бы сказал, что нет никакой ценности. Эта информация также может быть получена с помощью вашей функции комментирования/вины SCM. Кроме того, каждый может добавить текст между этими комментариями, что делает комментарии датированными (поскольку вы можете добавить что-то для v2.6, в то время как комментарии говорят v2.5)

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

Ответ 4

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

Ответ 5

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

Ответ 6

Может быть полезно в некоторых случаях (например, если это помогает понять, почему какая-то функция работает по-разному в V3, чем в V2), но в целом, это задача SCM знать, что было добавлено, когда.

Ответ 7

Ты не придирчивый ИМХО. Есть по крайней мере три веские причины не добавлять этот тип комментария в исходный код:

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

Линия неясна, хотя какая разница между

// Compliance with specs abc (additional xyz feature)
...
... // some code

и

// xyz feature:
...
... // some code

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

Мой совет: написали методический документ или неофициальное обсуждение.

Ответ 8

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

Тем не менее, я согласен с тем, что такие комментарии в основном бесполезны. Если использовать последовательно, программа быстро станет лабиринтом таких комментариев. Что делать, если строка изменяется один раз для версии 2.5, а затем через год снова изменилась ошибка 3294? Вы помещаете два комментария "версии" в одну строку или просто сохраняете последнее? Если вы сохраняете только последние, то вы потеряли тот факт, что это было первоначально добавлено для 2.5. Если вы держите их обоих, что происходит, когда происходит третье изменение или четвертое? Откуда мы знаем, какое состояние было при каждом изменении? Что происходит, когда вы добавляете блок кода в версию 2.5, а затем для версии 2.6 вы добавляете еще один блок кода, встроенный в блок 2.5? Etc и т.д. Программа может легко получить больше комментариев к версии, чем строки кода.

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

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

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

Вы могли бы сказать, что это может помочь уметь сказать: "Ох, это было добавлено к заказу, чтобы поддержать новую функцию timecard продавца" или некоторые такие. Но тогда важно, чтобы это не было: "Этот код был изменен Бобом для версии 3.2.4", а скорее "Этот код создает эти данные, которые здесь не используются, но необходимы другому модулю"

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

Ответ 9

Учтите, что некоторым может потребоваться захват снимков из VCS. В этом случае у них нет истории, чтобы отпасть... и такие комментарии станут полезными.

Ответ 10

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

Другая причина, по которой я нашел, - это то, что когда-нибудь важно знать, какая часть кода связана с какой версией. Конечно, вы всегда можете проверить журнал версий, но у вас не всегда есть время для этого, и это раздражает. В некоторых случаях выражение "code for v3.2" больше относится к другим разработчикам, чем "код для выполнения x, y и z"... все зависит от соглашений, установленных командой.

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

Ответ 11

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

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

В других работах, которые проще:

// DEF43562 - changed default value
foobar = true

или

  • винить (или equiv)
  • преследовать чтобы найти правильные изменения.
  • Следуйте интеграции с источником и повторить 1 & 2.
  • Найти идентификатор ошибки к оригинальному изменению, если вы повезло.

В основном комментарий представляет собой короткий отрезок вокруг VCS и flaky интеграции VCS/BugTracking.

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