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

StackOverflow https://stackoverflow.com/questions/648972

Вопрос

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

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

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

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

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

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

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

Это было полезно?

Решение

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

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

Другие советы

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

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

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

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

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

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

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

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

В коде, над которым я работаю, был этап, еще в период 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 тоже пришлось бы исправлять код. Комментарий помог - убедил меня, что ошибка была подлинной - но раздражает.

Лицензировано под: CC-BY-SA с атрибуция
Не связан с StackOverflow
scroll top