コメントの書き方

Doxygenで文書を作れるようにしようと思っているが、コメントが文書になるので色々と悩む。

文体としてどれがいいか。

• ナントカの値 （動詞を含まない）
• ナントカの値を取得 （意味は動詞だが、名詞で終わる、体言止め）
• ナントカの値を取得する
• ナントカの値を返す （能動態）
• ナントカの値が返される （受動態）

それと、句読点をどうするか。短いコメントの後に「。」を付けるか？

• ナントカの値。
• ナントカの値を取得。
• ナントカの値を取得する。
• ナントカの値を返す。
• ナントカの値が返される。

名詞や体言止めだと句点は要らないだろう。主語・述語（動詞による記述）がある文なら句点を付けるべきか？

Doxygenの長いコメントはWiki記法（Doxygen markdown）で書けるので、ここは通常の句読点ありの文章とすべきだろう。brief、特に体言止めのときの句読点が問題だ。つうか、体言止めがいいかどうか、という問題もある。

ルール決めておかないと、後から直すのはすごく大変。

[追記]

変数、例えばバッファのコメント

• ナントカを読み込んだ結果を入れる
• ナントカを読み込んだ結果が入る
• ナントカを読み込んだ結果を収める
• ナントカを読み込んだ結果を格納する

どうでもいいっちゃ、そうだが。気になりだすと気になるのだ。

[/追記]