phpのドキュメント書いていますか?

phpのドキュメント書いていますか?

最近保守の案件で他社様で作られたPHPソースを覗くことがよくあるのですが、ソース内にphpdocが書かれていないソースが多々あります。

(もちろん開発中には書かれていて本番リリース時に削除された可能性も否めませんが。)

phpdocは簡単でいいので必ず書きましょう。

 

phpdocを書くメリットって?

phpdocを書くメリットには次のものがあります

  1. 後にソースを見返した時理解する時間が短縮される
  2. phpstormと併用することでコーディング時に「変数の型の間違い」等の凡ミスをを防げる
  3. 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

 

 

phpのドキュメント書いていますか?
Tagged on:             

コメントを残す

メールアドレスが公開されることはありません。 が付いている欄は必須項目です