Комментарии контроля версий - прошедшее или настоящее время [закрыто]

12

Для комментариев контроля версий, что другие пользователи рекомендуют - прошедшее или настоящее время?

Т.е.

  • Изменено х на у.
  • или
  • Меняем x на y.
Роберт У
источник
27
Разве вы не имеете в виду «контроль версий, проверяющий комментарии»? Я никогда не добавляю комментарии, документирующие изменения в реальном коде. Это загромождает это.
JohnFx
1
Я действительно сбит с толку - если @JohnFx верен, то это совершенно другой вопрос. Лично я не понимаю, почему @Robert не мог иметь в виду комментарии в исходном коде.
Арманд
К вашему сведению: я имел в виду «Регистрация», а не «проверка»
JohnFx
Извините - просто чтобы устранить путаницу, я имел в виду комментарии контроля версий, а не комментарии в исходном коде. Вопрос был обновлен.
Роберт W

Ответы:

19

Комментарии следует читать в контексте, поэтому:

настоящее время

Для исходных комментариев выше метода или до появления какого-либо поведения:

// This function does X
function doX() { ... }

прошлое

Для комментариев источника после некоторого поведения произошло

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

И для фиксации сообщений

функция X изменена


Смешанный пример:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}
Armand
источник
NB. Я думаю, что все комментарии в приведенном выше коде излишни, но они не обязательно будут в нетривиальном примере.
Арманд
7
Теперь вопрос изменился, этот ответ немного не по теме.
Арманд
22

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

Формулировка чего-либо как «Изменение» подразумевает, что вы в настоящее время вносите изменения и что код может быть не завершен.

примечание: лично я добавляю комментарии к изменениям только тогда, когда произошли радикальные изменения.

Тим
источник
10

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

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

Я настоятельно рекомендую, чтобы единственными комментариями в вашем коде были то, что требуется для понимания самого кода - цель, бизнес-логика и исключительные случаи. Оставьте документацию об изменениях в вашей системе контроля версий. Если вы не используете VCS, начните прямо сейчас. Существует несколько бесплатных высококачественных VCS (Subversion, Mercurial, Git и т. Д.).

Берин Лорич
источник
3
+1, хотя я думаю, что комментарии по управлению версиями тоже должны быть в прошедшем времени. :-)
Эрик Кинг,
Не так уж плохо иметь отдельный файл журнала изменений; помещать туда комментарии коммитов не будет слишком больно, но разбрызгивание их по каждому файлу - просто болезненный шум.
Donal Fellows
Совершать сообщения можно в любом случае. Я склонен смотреть на это, поскольку это было настоящее действие по причине совершения в то время. В конце концов, это область английского языка, в которой, вероятно, ничего страшного, чтобы не разбить волосы. Это не похоже на «ест, стреляет и уходит» en.wikipedia.org/wiki/Eats,_Shoots_%26_Leaves
Берин Лорич,
10

Я использую императив настоящего времени, так что-то вроде:

Измените «х» на «у»

Это рекомендуется разработчиками Git:

  • тело должно предоставить содержательное сообщение о коммите, которое:
    • использует императив настоящего времени: «изменить», а не «изменить» или «изменения».

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

mipadi
источник
1
Я согласен, что сначала это кажется странным, и просмотр его как патча - определенно верный путь. Одна вещь, которую я делал, это читал «Этот патч будет» в моей голове перед тем, как прочитать мое сообщение о коммите. Это переход от вопроса к себе: «Что я делал в этом патче?» (Исправлена ​​ошибка с многопоточностью), когда вы спрашивали себя: «Что сделает этот патч?» (Исправлена ​​ошибка потоков).
Ник Ноулсон
5

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

ГРАММ__
источник
2

Комментарии к коду должны быть естественными для чтения.

Если вы читаете код , говорите себе «Этот код будет делать X» , то вы должны написать комментарий в настоящее время , как это, вероятно , как кто - то читает код в то время будет думать , как хорошо. Если, с другой стороны, вы в какой-то момент думали: «Этот код сделал X», то это должно быть в прошедшем времени. В конце концов, все сводится к личным предпочтениям, если только по какой-то причине у вас нет указаний о том, как комментировать ваш код (например, для командного проекта или для класса и т. Д.).

Кеннет
источник
1

Если вы используете git, соглашение состоит в том, чтобы использовать настоящее время, потому что сообщения коммитов, сгенерированные с помощью инструментов git (например, слияние), используют настоящее время.


источник
1

Вы должны использовать прошедшее время.

Причина в том, что вы отвечаете на вопрос, чего достиг этот коммит? Думайте об этом, как о том, что вы рассказываете своей VCS:

Совершить 123
Изменено XYZ, чтобы сделать ABC

Чтобы привести контрпримеры, использование будущего времени звучит так, будто вы просите кого-то сделать это:

Совершить 123
Изменить XYZ на ABC

и использование настоящего времени звучит так, будто вы на полпути:

Совершить 123
Изменение XYZ, чтобы сделать ABC

Гарри Шутлер
источник
0

Используйте настоящее время: «Измените X на Y», почти как если бы это был элемент в чистом списке TODO.

В общем, как в сценарии, избегайте глаголов типа «быть» и «есть». Например, это не «он ходит», а «он ходит».

Но в этом конкретном примере - если вы говорите о комментариях к коду, а не о комментариях регистрации - я считаю, что «Изменить X на Y» - ужасный комментарий. Он не добавляет никакой новой информации, и если код будет изменен, он может быть даже неверным. Лучше, если вы извлечете код в метод (или класс), а затем документируете этот метод. Если это достаточно ясно, тогда достаточно хорошего имени метода.

Говоря о том, что для документирования методов вы могли бы использовать будущее время, например: «Если предоставленное число является отрицательным, absвернет величину числа».

Макнейл
источник
0

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

Комментарии к настоящему времени ( .ie «он меняется» или «он меняется» ) указывает на то, что часть данных, управляемая задокументированным алгоритмом, каким-то образом подвергается воздействию. Таким образом, это указывает, что код делает или что происходит с данными, которыми манипулируют.

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

Ввод уже был проверен перед вводом этого блока кода

или

Данные были записаны в файл в конце исполняемого кода.

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

Комментарии в прошедшем времени, указывающие на изменение самого кода (.ie. X был изменен на Y ), не должны существовать в коде. Вместо этого они должны существовать как комментарии к редакции в репозитории исходного кода.

Комментарии в будущем должны указывать на условие, которое должно быть выполнено или выполнено, но по X или Y причине не выполняется сейчас. Например:

Когда мы, наконец, мигрируем БД, нам придется изменить эту логику

или

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

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

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

luis.espinal
источник
0

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

  • Комментарии, описывающие желаемое поведение, принимают форму императивного предложения настоящего времени.

    // Calculate the width of the curve at x height.
    
  • Используйте набор ключевых слов из всех заглавных букв для описания общих тем в коде (и для упрощения поиска):

    // NOTE: <This code was written this way for a reason.>
    // TODO: <This code is incomplete. Finish it.>
    // HACK: <This code was written this way for a reason that you won't like.>
    // FIXME: <This code has a known flaw. Fix it.>
    
Кодзиро
источник