コメント

コメントは英語で書きコメントを解析するツールのために 以下のような正規化をおこないます。 たとえばチュートリアルにおける変数一覧などがこれらの情報から作られています。 また、引数宣言との矛盾チェッカなどもこれらのコメントを参考にしています。

メソッドが public か private かに関わらず、 コメントは少なくとも以下の要素を持つべきです。

# Descriptions: 
#    Arguments: $self $args
# Side Effects: 
# Return Value: none

// Descriptions: 
//    Arguments: $self $args
// Side Effects: 
// Return Value: none

/*
 * Descriptions: 
 *    Arguments: $self $args 
 * Side Effects: 
 * Return Value: none
 */

perl の場合、 public メソッドについてはコメント以外にも 公式な説明を POD 形式で書くようにしています。

OBJ($curproc)
STR($buf)

記法   なに？              perl の内部表現  
----------------------------------------------------------
OBJ    オブジェクト        (bless できれば、どんな型でもあり得る)

STR    文字列              (PV (SV の特別なもの))
NUM    数字                (SV)
ARRAY  配列                (AV)
HASH   ハッシュ            (HV)
HANDLE ファイルハンドル類  (GV)

STR_REF
ARRAY_REF
HASH_REF