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

B!

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 値を返さない
null NULL値
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

 

 

最新の記事はこちらから