フリーソフト

« 命名規則 | トップページ | 書式 »

コメント

このドキュメントは、Google C++ Style Guideを翻訳、要約したものです。省略した部分や意訳した部分が多くあります。原文の意図が伝わるよう注意しましたが、誤りが含まれているかもしれません。正確な情報については、必ず原文を参照してください。

前へ | 目次 | 次へ

コメント

コードを読みやすくキープするためにはコメントは必須である。ここでは何をどこにコメントすべきかを記述する。しかし、最良のコメントとはコード自身がドキュメントになっているものである。コメントで説明しなくてはならないあいまいな変数名を使用するよりも、分かりやすい名前を付ける方がはるかによい。

コメントは、次の貢献者のことを考えて書くこと。寛大であれ。次の貢献者はあなた自身かもしれない。

コメントのスタイル

// もしくは /* */ 構文を使用する。// がより一般的である。コメントの内容や、どの構文をどこで使うかなど、一貫性を保つこと。

ファイルのコメント

各ファイルはライセンスの決まり文句から始め、そのあとにファイルの説明を書くこと。

法律上の注意事項と著者表示

すべてのファイルにライセンスの常用文を含めること。プロジェクトで使用するライセンス(例:Apache 2.0、BSD、LGPL、GPL)に適した常用文を選択すること。ファイルを大幅に変更する場合は、著者表示の削除を検討すること。

ファイル内容

ファイル内容を説明するコメントをファイルの上部に必ず書くこと。

通常、.hファイルにはクラスの目的や使用方法の概要を記述する。.ccファイルには、実装の詳細やトリッキーなアルゴリズムに関する議論といった詳細な情報を記述する。.ccではなく .hに詳細な情報を書いた方がよいと考えられる場合はそうしてもよい。ただしその場合は、.hにドキュメントがあることを .ccファイルに書かなくてはならない。また、.hと .ccに重複したコメントを書いてはならない。

クラスのコメント

クラス定義のコメントには、クラスの目的と使用方法を記述すること。

ファイルの先頭にクラスの詳細なコメントが記述済みの場合は、単純に「詳しい説明はファイルの先頭を参照のこと」と書いておく。必ず何かのコメントは書いておくこと。

クラスの同期処理の仮定をドキュメント化すること。クラスのインスタンスが複数のスレッドからアクセスできる場合は、利用ルールとマルチスレッド処理における不変量について注意してドキュメント化すること。

関数のコメント

関数の宣言部分のコメントには、関数の使い方を記述すること。関数の定義部分のコメントには、関数の処理内容を記述すること。

関数宣言

関数宣言の直前にコメントを記述すること。コメントには、関数の目的と使い方を書くこと。これらのコメントは、命令的("Open the file”)ではなく記述的(”Opens the file”)にすること。一般的に、ここでは関数の処理内容については記述しない。

関数宣言のコメントに記述すべき内容は以下のとおり。

  • 入力が何で、出力が何であるか。
  • クラスのメンバ関数について:メソッド呼び出し後も参照引数を覚えているのか、それらをfreeするのかしないのか。
  • 関数がメモリを割り当てる場合、呼び出し側で解放する必要があるのか。
  • 引数にNULLポインタを渡すことができるのか。
  • 関数の使い方によってパフォーマンスに影響がでるのか。
  • 関数は再入可能なのか。同期の仮定は何か。

自明なコメントは省略すること。デストラクタにヘッダのコメントがないことはよくあること。「オブジェクトを破棄する」といったコメントは不要。

関数定義

何かしらトリッキーな処理がある場合は、関数定義のコメントで説明すること。処理ステップの概要や、なぜその方法で実装したのかについて説明する。

.hファイルと重複したコメントを記述しないこと。関数が何をするかについて簡単に要約することは問題ないが、コメントの重点はそれをどのようにやるかについてである。

変数のコメント

変数名は、その変数が何に使われるのかが分かるようなものにすること。必要に応じてコメントを書くこと。

クラスのデータメンバ

クラスのデータメンバ(インスタンス変数、メンバ変数)には、何のために使われるのかを説明するコメントをつけること。変数が特別な意味を持つ値(nullポインタや-1)をとる場合は説明を書くこと。

グローバル変数

データメンバと同様、その変数が何のために使用されるのかを説明するコメントをつけること。

実装のコメント

コードのトリッキーな部分、不明瞭な部分、興味深い部分、重要な部分にはコメントを書くこと。

説明のためのコメント

トリッキーなコードや複雑なコードには、それらの前にコメントを書くこと。

行コメント

不明瞭な行には行の後ろにコメントを書くこと。コードの行末とコメントの間は空白2つで区切ること。

nullptr/NULL, true/false, 1, 2, 3...

nullポインタや論理値、整数リテラルを関数に渡す場合は、それらが何であるかをコメントに記述すること。あるいは、定数を使用するなどしてコード自体に意味を持たせること。

やってはいけないこと

コード自体を説明してはならない(コードを見れば明らかなことはコメントしない)。

句読点、綴り、文法

句読点、綴り、文法に注意を払うこと。きちんと書かれているコメントほど読みやすい。

断片的な文よりも完全な文のほうが読みやすい。文末コメントのような短いコメントについては多少崩れてもよいが、スタイルに一貫性を持つこと。

TODOコメント

一時的なコード、短期的な解決策、十分であるが完全ではないコードに対しては、TODOコメントを使用すること。

TODOコメントは、すべて大文字の文字列「TODO」から始め、そのあとに名前やEメールアドレスなど、この問題の事情を一番よく知る人物の情報を書く。TODOの主目的は、より詳細な情報を獲得するための方法を提供することである。TODOに名前がある人に、問題を修正する責任があるという意味ではない。あなたがTODOコメントを書くときは、あなたの名前を書いておくこと。

// TODO(kl@gmail.com): 2005年11月までに修正

TODOが「将来何かをする」というような内容の場合は、具体的な日付を書くか(例:2005年11月までに修正)、具体的なイベントを書くこと(例:全クライアントがXMLレスポンスを処理できた時点でこのコードを取り除く)。

非推奨コメント

非推奨のインタフェースにはDEPRECATEDコメントをつけること。

DEPRECATEDコメントは、すべて大文字の単語「DEPRECATED」から始め、そのあとに丸かっこで名前やEメールアドレスなどを書く。コメントは、インタフェース宣言の前か、同じ行に書く。

呼び出し側のコードを修正する人のために、DEPRECATEDコメントはシンプルで明確な指示とすること。非推奨関数を、新しいインタフェースを呼び出すようなインライン関数として実装してもよい。

新規のコードは非推奨インタフェースの呼び出しを含んではならない。代わりに新しいインタフェースを使用すること。指示が理解できない場合は、DEPRECATEDコメントを書いたい人に確認すること。

前へ | 目次 | 次へ

« 命名規則 | トップページ | 書式 »

技術文書」カテゴリの記事