【PHPerなら書けるでしょ?】PHPのDocコメントについて今更学んでみた

PHPer は技術者のレベルの差が激しいと言われている言語です。

恥ずかしい思いをしないためにもDocコメントの基礎くらいは知っておきたいところです。

Docコメントのメリット

可読性・視認性が高くなる

何をするのか・どのようなデータを持っているのかなどが一目で分かる。

一目でわかるこそ、保守開発時には大いに役に立チマス。(正直これだけ書くモチベーションになれます。

ツールに影響する

PHPStan や PHPUnit などのツールを使用する際に大きく役に立つ。

特に静的解析の精度向上に役に立ち、バグの発生や早期発見にすんげぇ貢献してくれる。

Docコメントのデメリット

めんどくさい

Docコメントを書く事が猛烈にめんどくさい日がたまにあります。

メリットをちゃんと理解しているので、めんどくさい日でもちゃんと書きます。みなさんも書きましょう。

不適切な内容だとツラい

Docコメントに書いてある内容が間違っていると誤解を生み、新たな仕事を発生させることがある。

最近ではある大手のサービスのSDKのDocコメントが間違っており、IDE上の警告が消えないために時間を費やしてしまう事件がありました。(多分Docコメントのメンテナンスされていないだけかな…?)

みんなもキヲツケテネ。

書き方

こんな感じで書くよ。(改行がおかしいのは許してね)

/**
* 何をするメソッドなのか 
*
* @param 変数
* @return 戻り値
*/
private function fuga(): void {}



/**
* プロパティの説明
*
* @var string
*/
protected string $hogehoge

 

型定義

type説明
string文字列
integer / int整数
boolean / bool真偽値
float / double浮動小数点数
object任意のクラスのインスタンス
mixed任意の型(不特定)
array配列
resourceリソース型
void値を返さない
nullNULL値
callableコールバック関数
false / true真または偽
self同じクラスのインスタンス
scalarスカラー型(string, int, boolなど)

参考:https://docs.phpdoc.org/3.0/guide/references/phpdoc/types.html

タグの意味

Tag Name意味用法の例
@paramパラメータを記述
※メソッドのDocコメントに使ったりするよ
@param int $age 年齢
@return戻り値を記述@return string ユーザーの名前を返します
@var変数の型を記述
※プロパティのDocコメントに使ったりするよ
@var string $name ユーザーの名前
@throws例外を記述@throws InvalidArgumentException 不正な引数の場合
@deprecated非推奨を示す@deprecated 2.0.0バージョン以降で非推奨
@see関連要素を参照@see User::getName() 関連するメソッド
@author作者名@author 山田太郎
@since導入されたバージョン@since 1.0.0 初期バージョンから導入
@versionバージョン@version 1.2.3
@link関連リンク@link http://example.com 詳細情報
@example例示@example /path/to/example.php 例示コード
@categoryカテゴリ分類@category HTTP クライアント関連

参考:https://docs.phpdoc.org/3.0/guide/references/phpdoc/index.html

 

 

Twitterでフォローしよう

読んでみーな
おすすめの記事