phpのドキュメント書いていますか？
最近保守の案件で他社様で作られたPHPソースを覗くことがよくあるのですが、ソース内にphpdocが書かれていないソースが多々あります。
（もちろん開発中には書かれていて本番リリース時に削除された可能性も否めませんが。）
phpdocは簡単でいいので必ず書きましょう。
phpdocを書くメリットって？
phpdocを書くメリットには次のものがあります
- 後にソースを見返した時理解する時間が短縮される
- phpstormと併用することでコーディング時に「変数の型の間違い」等の凡ミスをを防げる
- phpunitによるユニットテストのテスト項目をphpdocから生成できる
1. は言わずもがなですね、ただ個人的には「テキストによるプログラムの情報が記載されている」というメリットより、「どんな（レベルの）人間がソースを書いたのかをより知る事が出来る」というメリットの方が大きいと思います。
2. は PHPMDをインストールすることで実現できます。
3. は次回に紹介するとして、ここでは2. PHPMDとの併用を紹介していきましょう
PHPMD（PHP Mess Detector）とは？
PHPMDはPHPの静的コード解析ツールでバグのもとになりそうな次の問題を教えてくれます
- 未使用の変数やメソッド
- 複雑過ぎるコード
- 美しくない命名
PHPMDのインストール
composerを使ってインストールします。
composer global require phpmd/phpmd
echo ‘export PATH=$HOME/.composer/vendor/bin:$PATH’ >> .bash_profile source .bash_profile
PHPMDを使用する
コマンドラインから使用してもいいのですが、エディタAtomやSublimeTextや\で使用すると、とても便利なのでこちらから使用します。
AtomにPHPMDをインストールする
apm install linter apm install linter-phpmd
Sublime TextにPHPMDをインストールする
Command + Shift + P から 「install」を入力して以下のパッケージをインストールする
SublimeLinter
SublimeLinter-phpmd
これでエディタで .php ファイルを開くと自動的にPHPMDによる解析が行われるようになります。
PHPMD動作例01（Sublime Text編）
PHPMDは以下のように動作します
上記の例では 引数 $arg1 , $arg2 が使われていません。
PHP構文的にはエラーとなりませんが、使用しないのに引数 $arg1 , $arg2 を受け付けているのはおかしいので削除するべきです。
こういったおかしいコードを PHPMD は指摘してくれます。
PHPMD動作例02（phpstormとの併用）
phpstormを使用している場合は phpdoc に記述の変数と実際のコードに一致しない記述がある場合にエラーを表示してくれます。
phpdocとphpunit有効活用
こちらのページにいい方法が記述されています。
是非活用しましょう
DocCommentでPHPのユニットテストの書きやすさを劇的に改善する手法 – pixiv inside