バージョン管理のコメントについて、他のユーザーは何をしますか/推奨します-過去形または現在形？

すなわち

• xをyに変更しました。
• または
• 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など）。

私は命令形の現在時制を使用しているので、次のようなものです：

「x」を「y」に変更します

これはGit開発者によって推奨されています：

• 本文は、意味のあるコミットメッセージを提供する必要があります。
  • 「変更」または「変更」ではなく、「変更」という命令形の現在時制を使用します。

最初は少し奇妙に思えるかもしれませんが、コミットを何かを行うパッチと考えるなら、それはより理にかなっています。（これは、GitのようなDVCSで特に当てはまります。DVCSでは、リポジトリで行動する他の人からチェンジセットを取得します。）

本当に問題ではありません。個人的なスタイルと好みだと思います。ほとんど何でも書いているように、自分自身や他のコメントと一致するようにしてください。

コードのコメントは読みやすいものでなければなりません。

「このコードは Xを実行しています」というコードを読んでいる場合は、現在の時制でコメントを書く必要があります。他方で「このコードは Xを実行した」という特定の時点で考えていた場合、それは時制を過ぎているはずです。最終的には、何らかの理由でコードをコメントする方法のガイドライン（つまり、チームプロジェクトやクラスなど）にない限り、個人的な好みになります。

gitを使用している場合、慣例は現在形を使用することです。これは、gitツール（たとえば、マージ）で生成されたコミットメッセージが現在形を使用するためです。

過去形を使用する必要があります。

このコミットが何を達成したのかという質問に答えているという理由はありますか？VCSに何をしたかを伝えると考えてください。

コミット123
XYZをABCに変更

反例として、未来形を使用すると、他の誰かにそれを依頼しているように聞こえます。

ABCを行うためにXYZの変更123をコミット

そして現在の時制を使用すると、あなたはそれの途中にいるように聞こえます：

コミット123
XYZの変更によるABCの実行

現在の時制：「XをYに変更」を使用して、まるで明確なTODOリストのアイテムであるかのように。

一般に、脚本のように、「to be」や「is」などの動詞を避けます。たとえば、「彼は歩いています」ではなく、「彼は歩いています」。

ただし、この特定の例では、チェックインコメントではなくコードコメントについて話している場合、「XからYへの変更」はひどいコメントだと思います。新しい情報は追加されません。また、コードが変更された場合、間違っている可能性もあります。コードをメソッド（またはクラス）に抽出し、代わりにそのメソッドを文書化する方が良いでしょう。明確な場合は、適切なメソッド名で十分です。

そういえば、メソッドを文書化するために、将来の時制を使用できます。たとえば、「指定された数値が負の場合、数値absの大きさを返します」。

コメントは、書かれたものと同様に、何かの表現と同様であり、自然言語の同じルールに従う必要があります（文書化される状況またはアーティファクトに固有の略記と略語を考慮に入れる必要があります）。

現在形に関するコメント（.it "it changes"または "it is changing"）は、文書化されたアルゴリズムによって操作されているデータが何らかの形で影響を受けていることを示しています。つまり、コードが何をしているか、または操作されているデータに対して何が起こっているかを示します。

過去時制のコメントは、コメントが存在するポイントの前に発生した何かのアサーション、前提条件、または事後条件を示す必要があります。例えば：

このコードブロックを入力する前に、入力が既に検証されています

または

実行中のこのコードの終わりにデータがファイルに書き込まれました

過去形のコメントは、何かが行われている理由を説明することもできます（この関数は、レガシーデータベースの問題に対処するためにXとYを行います。）

コード自体への変更（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.>