Kosei Kitahara avatar Kosei Kitahara committed 5c35d6c

Update Comments to Rev 2.29.

Comments (0)

Files changed (1)

 コメント
 ````````
 
+モジュール、関数、メソッドおよび行のコメントは正しいスタイルを利用する。
+
 .. _コメント_ドキュメンテーション文字列 (Doc Strings):
 
 ドキュメンテーション文字列 (Doc Strings)
 関数及びメソッド
 ''''''''''''''''
 
-一見わかりにくかったり、長い関数やメソッドはドキュメンテーション文字列が必要です。
-それに加え、一目で理解できたり、短い関数であっても、外部からアクセス可能な関数やメソッドであればドキュメンテーション文字列が必要です。
-ドキュメンテーション文字列は関数の動作と入出力の詳しい解説を含む必要があります。
-それは通常、そのアルゴリズムが複雑でない限りその動作について詳しく解説する必要はありません。
-コード内の効果的なコードブロックやインラインコメントを利用することでよりよくなります。
-ドキュメンテーション文字列は、コードを 1 行も見ることなく、その関数を呼び出すための十分な情報が記載されている必要があります。
-引数は、2 もしくは 4 つのぶら下げインデントで縦にそろえ、コロンの後にその説明を記載する必要があります。
-ドキュメンテーション文字列は、期待される戻り値の型を指定します。
-"Raises:" 部分には関数により発生する可能性があるすべての例外を列挙します。
-ジェネレータ関数のドキュメンテーション文字列は "Returns:" よりも "Yields:" を使います。 ::
+このセクションの "関数" はメソッド、関数、及びジェネレータに摘要されます。
 
+関数が次のすべての条件にあてはまらない場合は、ドキュメンテーション文字列が必要です。
+
+* 外部から見えない
+* 短い
+* 明確
+
+ドキュメンテーション文字列は、コードを 1 行も見ることなく、
+その関数を呼び出すための十分な情報を記載します。
+ドキュメンテーション文字列は、関数を呼び出すための構文とそのセマンティクスではなく、その実装を記述します。
+トリッキーなコードには、ドキュメンテーション文字列よりもコードに添ったコメントの方が適しています。
+
+特定の関数は、以下のように特定のセクションで文書化します。
+各セクションはコロンで終わる見出し行で始まります。
+セクションの見出しを除いて、空白 2 文字でインデントします。
+
+Args:
+    各変数名の一覧を記載します。
+    名前の後に、コロンとスペースで区切った説明を書きます。
+    説明が 80 文字で収まらない場合は、2 文字か 4 文字のぶら下げインデントを使います。
+
+Returns: (ジェネレータの場合は Yields:)
+    型と戻り値のセマンティクスを説明します。
+    関数が `None` しか返さない場合は、このセクションは必須ではありません。
+
+Raises:
+    インターフェースに関連するすべての例外の一覧を記載します。
+
+::
     def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
         """Fetches rows from a Bigtable.
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.