Управление конфигурацией - история в комментариях к коду

Question

Позвольте мне изложить немного справочной информации, прежде чем задавать мой вопрос:

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

///<history>
   [mt] 3/15/2009  Made abc changes to fix xyz
///</history>

Их официальное назначение для стандарта комментирования состоит в том, что «комментарии обеспечивают прослеживаемость от требования к модификации кода».

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

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

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

Answer 1

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

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

Answer 2

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

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

Это избыточно? Да. Это ненужно? Нет.

Answer 3

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

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

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

Answer 4

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

Answer 5

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

Answer 6

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

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

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

    if (ctab->tarray && ctab->tarray[i])
#ifndef NT
      prt_theargs(*(ctab->tarray[i]));
#else
      /* Correct the parameter type mismatch in the line above */
      prt_theargs(ctab->tarray[i]);
#endif /* NT */

Команда NT получила правильный вызов; почему они думали, что это решение для платформы, мне не под силу. Конечно, если бы код использовал прототипы вместо просто объявлений без параметров, то команде Unix тоже пришлось бы исправлять код. Комментарий помог - убедил меня, что ошибка была подлинной - но раздражает.