関数/クラスコメント書式設定の規則

Question

最も読みやすく便利な関数/クラスコメント規約はありますか？ 私はドキュメントを生成するものは探していませんが、すべての情報がそこにあるので、JavaDocのようなものを採用することを検討しています。

/** 
* This function processes data 
* 
* @param p1 the first piece of data 
* @param p2 the second piece of data 
* @return true if the processing was successful, else false 
*/ 
function ProcessData(p1, p2){ 

または他の手作りのもの？

///////////////////////////////// 
// This function processes data 
// 
// p1 the first piece of data 
// p2 the second piece of data 
// returns true if processing was successful, else false 
function ProcessData(p1, p2){ 

複数行にわたる1行コメントについて合理的な議論はありますか？

私は使用しているすべての言語に慣習を適用したいので、言語固有または言語に依存しない慣習をご記入ください！

Answer 1

コメントスタイルの場合、私は間違いなくマルチラインに行きます

それぞれの情報の種類を指定できるので、最初の方がより強力です。「@タイプ名の説明」、「名前の説明」、そして通常はC言語で表示されます。

Answer 2

PythonはRSTを使用します。

Sphinxを使用すると、あなたが望むことができるかもしれません。

Answer 3

p1とp2に意味のある自明の名前を付けることをお勧めします。

「hereと同じように、コメントはシンドラーのリストではありません。純粋なものではなく、最高でも必要な悪です」