web-dev-qa-db-ja.com

バージョン管理コメント-過去形または現在形

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

つまり.

  • 変更 xがyになる。
  • または
  • Changing xはyになります。
commentssource-code
12
Robert W

コメントは文脈で読む必要があるので、

プレゼント

メソッドの上のソースコメント、またはいくつかの動作が発生する前：

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

過去-将来それを読む人は誰でも、過去に起こったように変更の行為を参照するでしょう。

「変更中」と表現することは、現在変更を加えている最中であり、コードが完成していない可能性があることを意味します。

note：個人的には、大幅な変更が発生した場合にのみ変更コメントを入力します。

22
Tim

コメントは静的なものなので、プログラムの状態現状のままを提示する必要があり、そうではありません。特定の質問に答えるには、過去形を使用する方が適切です。

ただし、このタイプのコメントは、バージョン管理システムに適しています。バージョン管理は、手動コメントよりもはるかに優れた変更追跡を行います。バージョン管理システムでは、変更がコミットされた時点でコメントが適用されるため、現在形で文書化する方が適切です。しかし、どちらも機能します。

コード内のコメントは、コード自体を理解するために必要なもの（目的、ビジネスロジック、例外的なケース）のみにすることを強くお勧めします。変更セットのドキュメントはバージョン管理システムに任せてください。 VCSを使用していない場合は、今すぐ開始してください。無料の高品質VCSがいくつかあります（Subversion、Mercurial、Gitなど）。

10
Berin Loritsch

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

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

これはGit開発者による 推奨 です。

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

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

10
mipadi

それは本当に重要ではありません。個人的なスタイルや好みだと思います。ほとんど何でも書いているように、あなた自身と他のコメントで一貫性があると書いてください。

5
G__

コードのコメントは自然に読めるはずです。

「このコードis Xをしている」と自分に言っているコードを読んでいる場合は、コメントを現在時制で書く必要があります。これは、その時点でコードを読んでいる人も同様に考えているためです。 。一方、特定の時点で「このコードdid X」と考えていた場合、それは過去形になります。結局のところ、何らかの理由でコードにコメントする方法のガイドライン（つまり、チームプロジェクトやクラスなど）を除いては、個人的な好みに帰着します。

2
Kenneth

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

1
user19651

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

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

コミット12
XYZをABCに変更

反例を示すために、未来時制を使用すると、誰かにそれを行うように依頼しているように聞こえます。

コミット12
XYZをABCに変更

そして、現在の時制を使用すると、途中のように聞こえます。

コミット12
XYZをABCに変更

1
Garry Shutler

現在の時制を使用します。「XをYに変更」は、まるで明確なTODOリストの項目であるかのように使用します。

一般的には、脚本と同じように、「ある」、「ある」などの動詞は避けます。たとえば、「彼は歩いている」ではなく、「彼は歩いている」ということです。

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

そういえば、ドキュメント化の方法として、将来の時制を使用することができます。たとえば、「提供された数値が負の場合、absは数値の絶対値を返します。」

0
Macneil

コメントは、書かれたものと同じように（またはそうでなければならない）、何かの表現であり、それらは自然言語の同じ規則に従う必要があります（文書化される状況またはアーティファクトに固有の省略形および省略形を考慮に入れます）。

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

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

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

または

実行されているこのコードの最後にデータがファイルに書き込まれました

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

コード自体の変更を示す過去形のコメント（つまりXがYに変更された）は、コードに存在してはなりません。代わりに、ソースコードリポジトリにリビジョンコメントとして存在する必要があります。

将来のコメントは、満たすか対処する必要があるが、XまたはYの理由で現在行われていない条件を示す必要があります。例えば：

最終的にデータベースを移行するとき、このロジックを変更する必要があります

または

TODO：できるだけ早く、入力の検証を再確認してください-XまたはYタイプの入力では失敗する可能性があり、現在実装できない大規模な変更が必要になる可能性があります。

後の[〜＃〜] todo [〜＃〜]タイプのコメントの場合、そのような変更が実際に行われることを確認するために、他の形式のドキュメントが存在する必要があります行われます。あなたが欲しい最後のものは時間と空間で失われたTODOです：P

塩の粒でそれを取りなさい、しかし私が自分のコメントをするとき私が通常従う規則は通常それらです。

0
luis.espinal

コメントは人間とのコミュニケーションに関するものなので、一貫性は重要ですが、原則自体がコミュニケーションの邪魔をするときに原則に行き詰まることが重要ですnot。そうは言っても、私は以下の疑似標準を使用しています。

  • 望ましい行動を説明するコメントは、現在時制の命令文の形式をとります。

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