История изменений в файле

Question

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

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

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

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

Answer 1

Большинство систем контроля версий имеют команду «Annotate» или «обвинить». Он показывает, какой код изменялся с каждой ревизией.

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

Answer 2

Если комментарий чувствителен ко времени, не делайте этого, это плохая идея. Вместо этого оставьте комментарий к исходному файлу в системе контроля версий.

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

«Похоже, что строка ниже исправляет ошибку xyz, и восстановится, если возникнут непредвиденные проблемы»

Я понимаю, что в первую очередь это не очень описательный комментарий, а такие вещи в svn / cvs / etc. на самом деле очень удобно. Такой комментарий в коде сеет семена сомнения. Можно ли удалить комментарий? Является ли непредвиденная проблема, которая заставила меня оглянуться на код, связанный с этим комментарием? и т.д.

Answer 3

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

Всякий раз, когда вы начинаете указывать историю в настоящем (текущий код), вы напрашиваетесь на неприятности. Подумайте, как будет выглядеть область кода с большими изменениями, если в ней будет несколько изменений?!

Answer 4

Мне просто интересно, как знание того, что делает ИСПОЛЬЗУЕМАЯ программа, помогает понять это сейчас? Вы говорите, что это помогает читабельности. Как?

Теперь, когда что-то изменилось из-за того, что старый способ не сработал, а новый - нелогично, я думаю, что это должно быть прокомментировано в коде, потому что необходимо знать все время "Это не сработало не делай так больше. Я знаю, похоже, это будет иметь больше смысла. И все же не делай этого ». Иначе я не вижу, чтобы это помогло.

Answer 5

Не думайте, что комментирование изменений внутри кода когда-либо возможно в пояснительной форме.

Но я бы хотел сказать о "истории изменений в начале файла". Я сомневаюсь, что это полезно на всех. Если только я не хотел знать, с какими версиями файла сравнивать, чтобы увидеть разницу, которая была введена с какой-то задачей «NNNN» В начале файла находится строка «Дата NNNN - небольшое описание». И наш источник контроля может «сказать», кому и в какой версии была введена эта строка.
Поэтому без этой строки я бы просмотрел все версии, чтобы найти правильную.

Answer 6

Собираюсь получить ответ на этот вопрос сам.

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

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

/* ticket 101: add blink tag to headers, JF - 20010102 */

Вы можете положить в

/* make headers blink */

Довольно часто, когда люди перестают делать комментарии первого типа, они массово сокращают свои комментарии, и это плохо.

Answer 7

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

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

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

Answer 8

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