コメントの書き方

これって正解はないと思うんですが、よく数ヵ月後に自分が見たときに判るようにしろ的なことは聞きます。

自分で作成していたとしても半年後もしくは一年後に見ると、忘れてしまっているのでそれはもう別のものになっています。
ある程度の流れや自分のコーディングルールから、他の人がみるよりは早く把握は出来ると思いますが、それでも作成していた当時のようなスピードは当然のことながらありません。

そこでコメントを残すわけですが、独学で突っ走っていた私はコメントを

// コメント

という感じで残したりしておりました。
それは別にいいんですが、これが見難い・・・。
そこで

//
// コメント
//

というように余裕を持たせてみると意外と見やすい。
（と言うか今までが見にくかったので、見やすく見えるだけ）

そんなくだらない時期を経て今はコメント残す際の見易さ対策として以下のような感じで残すように心がけてます。

大項目

/* *****************************************
 * とっても便利関数詰め合わせ
 * 入れられた値を元にハッシュ値を返します
 * 戻り値：[md5] => [sha1] => [CRC32] => 
 * ************************************** /

/
 * POST値バリデーション
 * XSS/CSRF 対策を行います
 */

// 初期化

$dozaemon = ""; // おぼれた人の名前
$do_mokun = ""; // NHKマスコットの名前
$degarashi = ""; // 用済みのお茶葉

プログラム