2

最も読みやすく、便利な関数/クラスのコメント規則を持っているのは誰ですか? ドキュメントを生成するものを探しているわけではありませんが、すべての情報がそこにあるため、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){

複数行に対する単一行のコメントに対する合理的な議論はありますか?

私が使用するすべての言語に規則を適用したいので、言語固有または言語にとらわれない規則を共有してください。

4

3 に答える 3

2

コメント スタイルについては、複数行を使用することをお勧めします。それが目的なので、全体的に見栄えがよくなります。

パラメーターについては、最初のものがより強力です。各情報のタイプを指定できるためです:「@type name description」対「name description」であり、C タイプ言語で通常見られるものです。

于 2009-06-14T00:02:40.040 に答える
0

Python はRSTを使用します。

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

于 2009-06-14T00:57:53.853 に答える
-2

まったくコメントしないで、p1 と p2 にわかりやすい名前を付けることをお勧めします。

ここで述べたように、「コメントはシンドラーのリストではありません。コメントは純粋な善ではありません。せいぜい必要悪です」

于 2009-12-29T14:36:31.290 に答える