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

Т.е.

• Изменено х на у.
• или
• Меняем x на y.

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

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

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

// 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
    ....
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

или

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

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

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

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

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

или

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

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

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

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

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

  // 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.>