うまく設計されたプログラムは、コメントを読むだけで全体像と個々の機能を把握しやすいものです。
コメントは長々と書くものではなくて、プログラムを読み解く手助けとなる内容を必要最小限に収める程度で充分だったりします。
機能している部分をコメントにすることを「コメントアウトする」などと言います。
■ 一行コメント（単行コメント）
# 一行コメント記述法その２
２種類の書き方がある。どちらも機能的に同じ。
一行コメントは、書いた位置から行末までとなる。
ただし、コメントの途中にスクリプトの閉じタグ「?>」があればそこがスクリプトの終わりとなる。
上記のような「?>」を含む書き方はスクリプトがうまく動かないので、 コメントアウトしようとして一行コメントを使っても無駄ということになる。
'/<foo.*?\>/'因みにエスケープすれば回避できるヨン。
■ 複数行コメント
/* echo "Hello world."; echo 'ハローわあるど'; */
複数行コメント同士の入れ子はできない。一行コメントを含む複数に渡る行を複数行コメントで囲むことはできる。
複数行と言いながら、一行コメントよりも局所的なコメントもできる
}
このようにスペースの書ける部分ならどこにでもコメントを書ける
■ どう書くか
コメントは読みやすい必要がある。
ごちゃごちゃと邪魔なコメントよりもシンプルで解りやすく統一感のある記述を目指す
ということで、広く使われている書き方のパターンを参考にする。
上記サイトからイケてそうな記述を抜き出してみます。
まずDocumentation block（DocBlock） という記述が目に付きます。
/** * これがドキュメントブロック */ /** * ドキュメントブロックは * こんな感じで * 伸び～る */
これはプログラムの頭に書くプログラムについての説明や、関数やクラスなどの機能説明用に使うタイプのベーシックなもののようですね。
それから @foobar 形式のキーワードを使った記述も目に付きます。
目ぼしいものを抜き出してみます。
@access public or private
@author author name <author@email>
@copyright name date
@global type $globalvarname
@param type [$varname] description
@return type description
@link URL
@package package name
@see name of another element that can be documented,
produces a link to it in the documentation
@since a version or a date
@var type a data type for a class variable
@version version
恐らくそれぞれ以下のようなこと書けばよさそう
@access メソッドのアクセス権 @author 著者 @copyright 著作 @global グローバル変数の型 説明 @param 引数の型 説明 @return 戻り値の型 説明 @link 関連URL @package モジュール名 @see 関連する項目や関数など @since 最初のバージョンと日付 @var クラス変数の型 @version バージョン
アクセス権は、クラスの持つメソッドが外部からアクセスできるか隠蔽されているかに基づいてpublicかprivateを記述します。
型はinteger,float,double,array,boolean,string,object,resource,null,mixedなどを指定することになります。
バージョン管理にはCVSの$Id$や$Revision$タグなども使われたりします。
∵ プログラム全体のコメント
プログラムの頭には @author @copyright @global @link @package @since @version辺りが使えそうですね。
/** * このプログラムは○○を実現するためのもの * * @package モジュール名 * @auther myName * @copyright (c) 2010-2011 作者や所属団体名 * @version 1.0 */
∵ クラスのコメント
クラス説明には @author @copyright @package @since @versionなどが使えそうですね。
/**
* ××を実現するクラス
*
* @package モジュール名
* @auther 著作者
* @version 1.00
*/
class Foo
{
}
∵ メソッドのコメント
メソッド説明には @access @global @param @return などが使えそうですね。
class Foo
{
/**
* △△の機能
*
* @access public
* @param integer $x Ｘ座標
* @param integer $y Ｙ座標
* @return integer
*/
public function bar($x, $y) {
return $x * $y;
}
}
∵ メンバ変数（プロパティ）のコメント
メンバ変数には @varが使えそうです。@accessまで書いてしまうのは過剰でしょう。
class Foo
{
/**
* ファイルポインタを保持
*
* @var resource
*/
private $fp = null;
}
変数は羅列して一行コメントの方が見通しよさそうなのでこの書き方はあまりよくない？
クラス関連はここまで
∵ 関数のコメント
関数の場合はメソッドのアクセス権無しバージョンになるので機能説明の他、@paramと@returnが基本
/**
* △△の機能
*
* @param integer $x Ｘ座標
* @param integer $y Ｙ座標
* @return integer
*/
function bar ($x, $y) {
return $x * $y;
}
∵ 変数や定数のコメント
説明が必要な変数には、ドキュメントブロックを用意する必要があるかも知れません。
/** * 変数や定数の説明 * * @global integer fooの設定値 * @see 関連項目ａ,関連項目ｂ */ $foo_config = 1;
Eclipseのプロジェクト内で@foobar形式のキーワードを使ってコメントを書いておけば、コンテンツアシストが効果的に使えるらしい。