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

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

Я недавно присоединился к новой группе разработчиков программного обеспечения, которая использует рациональные инструменты для управления конфигурациями, включая систему управления версиями и систему управления изменениями. В дополнение к этим инструментам команда имеет стандартную практику отмечать любые изменения кода как комментарий в коде, например: 
///<history>
   [mt] 3/15/2009  Made abc changes to fix xyz
///</history>

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

Я готов выдвинуть аргумент, что эта практика является ненужной и избыточной; что команда должна немедленно избавиться от этого стандарта. Система управления изменениями-это место, где можно построить прослеживаемость от требования до модификации кода, а система управления версиями может обеспечить детальную историю изменений, выполняя различие между версиями. При регистрации исходного кода отмечается соответствующий билет управления изменениями. Когда билет CM разрешен, мы отмечаем, какие файлы исходного кода были изменены. Я считаю, что это обеспечивает достаточную перекрестную ссылку для желаемой прослеживаемости. Я хотел бы знать, если кто-то не согласен с моими аргументами. Может быть, я упускаю некоторые преимущества комментируемой истории исходного кода, которые не могут обеспечить системы управления изменениями и управления версиями?
6 5
coding-style configuration-management

6 ответов:

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

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

6

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

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

Это лишнее? Да. Это ненужно? №

4

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

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

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

2

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

1

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

1

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

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

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

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

0