Сопровождение кода: добавлять комментарии в код или просто оставлять его для контроля версий?

Нас попросили добавлять комментарии с начальными тегами, конечными тегами, описанием, решением и т. Д. Для каждого изменения, которое мы вносим в код как часть исправления ошибки / реализации CR.

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

Но мои лидеры настаивают на том, чтобы комментарии были «хорошей» практикой программирования. Один из их аргументов заключается в том, что, когда CR необходимо отменить / изменить, было бы обременительно, если бы там не было комментариев.

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

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

// begin fix for bug XXXXX on 10/9/2012
...
// end fix for bug XXXXX

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

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

Так что вместо

// fixed bug XXXXX on 10/9/2012

у вас может быть комментарий, который говорит

// doing X, because otherwise Y will break.

или

// doing X, because doing Y is 10 times slower.

Используйте лучший инструмент для работы. Ваша система контроля версий должна быть лучшим инструментом для записи, когда исправления и CR сделаны: она автоматически записывает дату и кто внес изменение; он никогда не забудет добавить сообщение (если вы настроили его для отправки сообщений о коммите); он никогда не аннотирует неправильную строку кода и не удаляет случайно комментарий. И если ваша система контроля версий уже работает лучше, чем ваши комментарии, глупо дублировать работу, добавляя комментарии.

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

Но не пропускайте комментарии полностью: Хорошие комментарии (не рабски документирующие каждый запуск / остановку / описание / решение каждого исправления и CR) улучшают читаемость кода. Например, для хитрого или непонятного кода, который вы добавляете для исправления ошибки, // fix ISSUE#413замечательно использовать комментарий формы, сообщающий людям, где можно найти дополнительную информацию в вашем трекере.

Комментарии в коде о том , что код находится в данный момент. Создание снимка в любой момент времени не должно ссылаться на старые (или, что еще хуже, будущие) версии кода.

Комментарии в VCS о том, как изменился код. Их следует читать как рассказ о развитии.

Теперь каждое изменение должно включать комментарии? в большинстве случаев да. Единственное исключение, которое я себе представляю, - это когда ожидаемое поведение было уже задокументировано, но не тем, что вы получили, из-за ошибки. Исправление делает существующие комментарии более точными, поэтому их не нужно менять. Сама ошибка должна быть задокументирована в истории заявок и комментариях к коммиту, но только в коде, если код выглядит странно. В этом случае // make sure <bad thing> doesn't happenдолжно быть достаточно.

Один тип комментариев, который я действительно ценю:

// Это реализовано для бизнес-правила 5 предложения 2

или что бы вы ни использовали, чтобы собрать свои требования.

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

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

Ваши лидеры правы, когда говорят, что комментарии - хорошая практика программирования, однако есть исключения. Добавление комментария для каждого внесенного вами изменения является одним из них. И вы правы, говоря, что это должно принадлежать системе контроля версий. Если вы должны хранить эти комментарии в одном месте, то VCS - это путь. Комментарии в исходном коде, как правило, стареют и не поддерживаются. Нет комментариев намного лучше, чем плохие комментарии. То, что вы не хотите, это иметь комментарии в обоих местах (в коде и VCS), которые не синхронизированы. Цель состоит в том, чтобы держать вещи СУХИМ, имея единый источник правды для изменений в коде.

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

Также подумайте, что происходит, когда вы перемещаете части кода. Один из разработчиков баз данных, с которым я работаю, находится в лагере, в котором «каждая строка SQL должна быть аннотирована ревизией, в которой она была изменена, и мы собираемся сделать отдельные истории ревизий для каждого файла, потому что тогда будет легче увидеть кто что изменил когда и почему ". То , что работает любопытный Сорт хорошо , когда изменение являетсяпо порядку смены отдельных строк. Это не очень хорошо работает, когда, как я недавно сделал, чтобы исправить серьезную проблему с производительностью, вы разбили части большого запроса на временные таблицы, а затем изменили порядок некоторых запросов, чтобы лучше соответствовать новому потоку кода. Конечно, различие с предыдущей версией было в значительной степени бессмысленным, поскольку в нем говорилось, что изменилось около двух третей файла, но комментарий к регистрации также был чем-то вроде «крупной реорганизации для устранения проблем с производительностью». К тому времени, когда вы посмотрели вручную на две версии, стало ясно, что большие части действительно были одинаковыми, только перемещались. (И для выполнения хранимой процедуры потребовалось от нескольких минут до нескольких секунд. К этому времени

За очень немногими исключениями, отслеживание изменений и ссылки на проблемы - это работа VCS, IMNSHO.

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

Однако, если есть неочевидное изменение, которое меняет логику - особенно существенно изменяет логику, сделанную кем-то другим неочевидным способом - может быть очень полезно добавить что-то вроде: «это изменение - сделать это и это из-за ошибки # 42742 ". Таким образом, когда кто-то смотрит на код и задается вопросом «почему это здесь? Это выглядит странно», у него есть некоторые указания прямо перед ним, и ему не нужно проводить расследование через VCS. Это также предотвращает ситуации, когда люди нарушают чужие изменения, потому что они знакомы со старым состоянием кода, но не замечают, что он был изменен с тех пор.

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

Любая информация отслеживания, которая может быть выведена из-под контроля версий, не должна дублироваться в тексте кода. Это относится к глупым идеям, таким как ключевые слова проверки RCS, например, $Log$и тому подобное .

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

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

Комментарии в коде должны быть минимальными и точными. Добавление дефекта / изменение информации не ценно. Вы должны использовать контроль версий для этого. Некоторое время Контроль версий предоставляет немного лучший способ изменения. Мы используем ClearCase UCM; Действия UCM создаются на основе номеров дефектов, области изменений и т. Д. (Например, дефект 29844_change_sql_to_handle_null).

Подробные комментарии предпочтительнее при регистрации заезда.

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

Pramagic Programmer и CleanCode ведут к следующему руководству

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