Project ICKX公式サイトでのdoc commentルール #PHP

Project ICKX公式サイトで用いているdoc commentルールのメモ。

人にとっての読みやすさを優先するため、元々のPHPDocなどでは強制されていない事を強制したりしています。

「そもそもDocCommentとは？」という方はこちらの良記事をどうぞ。
PHPにコメントを書かせる、あるいはDocComment入門 (前編)

関数、メソッド向けdoc commentルール

関数、メソッド向けのdoc commentは次の3つのブロックに分かれます。
例としてbin2hex関数のドキュメント内容を用います。

1ブロック目：要約部

関数、メソッドが持つ機能の要約を記載します。

全ての関数、メソッドは要約する内容があるため、このブロックは必須の内容となります。

1行で記述してください。
1行に収まりきらない場合、要約を超える内容を記述している可能性が高いです。
その場合、後述の説明部に内容を展開してください。
もしも、複数行の記述が必要な場合、"."(ドット)と空行を含めてはなりません。

bin2hexならば次の内容です。

バイナリのデータを16進表現に変換する

2ブロック目：説明部

要約では収まりきらない、関数、メソッドが持つ機能の詳細説明を記載します。

説明する内容が無い場合、このブロックは省略されます。
このブロックを記載する場合、前ブロックに対して1行空行を入れ、ブロックを明示的に分けます。

長文になったり、構造化された内容を記述したい場合、"."(ドット)と空行を含めず改行し、一つの塊となるようにしてください。
なお、！！注意！！といった形でのちに見る人のための注意、警告内容を記載することがあります。

bin2hexならば次の内容です。

str を16進表現に変換したASCII文字列を返します。変換は、上位ニブルからバイト毎に行われます。

タグ記述部

引数や返り値、参照先の指定など@からはじまるタグが存在する場合に記載します。

記載する内容が無い場合、このブロックは省略されます。
このブロックを記載する場合、前ブロックに対して1行空行を入れ、ブロックを明示的に分けます。

見やすさのためにtabbingして記述内容の頭をそろえましょう。

タグの並び順は「param」「return」「exception」「see」となります。

タグの中で次の二つは特に注意してください。

パラメータタグ：@param

@param から始まる引数を説明するタグ。

期待する引数の型、変数名、引数の説明は全て必ず記載してください。
フォーマットは次となります。

@param ${期待する引数の型} ${変数名} ${引数の説明}

bin2hexならば次の内容です。

str 文字列。

返り値タグ：@return

@return から始まる返り値を説明するタグ。

返り値の型、返り値の説明は全て必ず記載してください。
フォーマットは次となります。

@return ${返り値の型} ${返り値の説明}

bin2hexならば次の内容です。

指定した文字列を16進表現に変換したものを返します。

実例

bin2hex関数に記載されている内容を元に記述すると次のようになります。

/**
 * バイナリのデータを16進表現に変換する
 *
 * strを16進表現に変換したASCII文字列を返します。変換は、上位ニブルからバイト毎に行われます。
 *
 * @param   string  $str    文字列
 * @return  string  指定した文字列を16進表現に変換したもの
 * @see     hex2bin()
 * @see     pack()
 */
function bin2hex ($str) {

プロパティ、クラス定数向けdoc commentルール

プロパティ、クラス定数向けのdoc commentは1つのブロックで構成されます。

基本的な記述内容は関数、メソッド向けdoc commentのパラメータタグと同様になります。

1ブロック目：タグ記述部

プロパティ、クラス定数の型と説明を記載します。

プロパティ、クラス定数の型、説明の全てを記述する必要があります。
フォーマットは次となります。

@var    ${プロパティ、クラス定数の型}   ${プロパティ、クラス定数の説明}

なお、スタティックプロパティやクラス定数の場合はを追加します。

@static

実例

/**
 * @var string  スコープセパレータ
 * @static
 */
public const SCOPE_SEPARATOR    = ' ';

/**
 * @var \ickx\fw2\auth\http\AuthSession 認証セッション管理用インスタンス
 */
protected $authSession      = null;

/**
 * @property    bool    ログイン中かどうか
 * @static
 */
private static $_isLogin    = false;

クラス向けdoc commentルール

クラス向けのdoc commentは次の3つのブロックに分かれます。
基本的に関数、メソッド向けのものと同じものとなります。

1ブロック目：要約部

クラスが持つ責務の要約を記載します。

全てのクラスは要約する内容があるため、このブロックは必須の内容となります。

2ブロック目：説明部

要約では収まりきらない、クラスが持つ責務の詳細説明を記載します。

3ブロック目：タグ記述部

カテゴリや所属するパッケージ、作者やライセンス、バージョンなど@からはじまるタグが存在する場合に記載します。

見やすさのためにtabbingして記述内容の頭をそろえましょう。

実例

/**
 * OAuth2認証を扱います。
 *
 * @category    Flywheel2
 * @package     auth
 * @author      wakaba <wakabadou@gmail.com>
 * @license     http://opensource.org/licenses/MIT The MIT License MIT
 * @varsion     2.0.0
 */
class OAuth2 {

ファイル向けdoc commentルール

ファイル向けのdoc commentは2つのブロックで構成されます。

「開いたときにパッと目についてどの案件のファイルであるか判る」「Show the flagでもないが、共通のロゴを見る事になるため士気が上がる」事にメリットを感じる場合は導入すると良いでしょう。

1ブロック目：本文、要約部

このファイルの説明を行います。が、大抵の場合はクラスの説明で事足りているので、案件名やプロダクト名を書くだけで十分です。

Text to ASCII Art Generator (TAAG)などで生成したアスキーアートを設置するなどすると、案件後半で士気が上がる場合があります。

2ブロック目：タグ記述部

カテゴリや所属するパッケージ、作者やライセンス、バージョンなど@からはじまるタグが存在する場合に記載します。

見やすさのためにtabbingして記述内容の頭をそろえましょう。

実例

<?php
/**  ______ _                 _               _ ___
 *  |  ____| |               | |             | |__ \
 *  | |__  | |_   ___      __| |__   ___  ___| |  ) |
 *  |  __| | | | | \ \ /\ / /| '_ \ / _ \/ _ \ | / /
 *  | |    | | |_| |\ V  V / | | | |  __/  __/ |/ /_
 *  |_|    |_|\__, | \_/\_/  |_| |_|\___|\___|_|____|
 *             __/ |
 *            |___/
 *
 * Flywheel2: the inertia php framework
 *
 * @category    Flywheel2
 * @package     auth
 * @author      wakaba <wakabadou@gmail.com>
 * @copyright   2011- Wakabadou honpo (http://www.wakabadou.net/) / Project ICKX (https://ickx.jp/)
 * @license     http://opensource.org/licenses/MIT The MIT License MIT
 * @varsion     2.0.0
 */

実装上のコードブロックの区切りコメント

長大なメソッドやプロパティ定義部などに対して大まかなブロックを作り、理解を助ける為の区切りコメントです。
副次効果として、ブロックに必要な処理が集約されやすくなるため、見通しや保守性が向上する場合があります。

大きいコードブロックの先頭を意味するコメント

//==============================================
// 大きいコードブロックの先頭
//==============================================

小さいコードブロックの先頭を意味するコメント

//----------------------------------------------
// 小さいコードブロックの先頭
//----------------------------------------------

実例

//==============================================
// 初期化
//==============================================
//ベンダーディレクトリの割り出し
//併せて定数化
define('FW2_VENDOR_ROOT_DIR', preg_replace("/". str_replace("\\", "\\/", __NAMESPACE__) ."$/u", '', str_replace("\\", "/", __DIR__)));

//==============================================
// オートローダーの登録
//==============================================
// Twig用オートローダー登録
//----------------------------------------------
require implode('/', [FW2_VENDOR_ROOT_DIR, 'twig', 'twig', 'lib', 'Twig', 'Autoloader.php']);
\Twig_Autoloader::register();

//----------------------------------------------
// Flywheel用オートローダー登録
//----------------------------------------------
require implode('/', [FW2_VENDOR_ROOT_DIR, 'ickx', 'fw2', 'core', 'loader', 'class_loader_register.php']);
\ickx\fw2\core\loader\ClassLoader::Register();

不要になったコードを敢えて残す場合などのコメント範囲を指定するブロック

よく「RMSを使用していれば不要」とされ、切り捨てられがちですが、実運用上必要な「その後すぐ復帰するから一時的にコメントアウトしておきたい」コード範囲を示すためのコメント範囲ブロックです、

イレギュラー運用ですが、RMSが使えない場合でもある程度は履歴管理が出来ます。

STA（STARTの略）から始め、ENDで終わるようにします。
これはインデントレベルを合わせて人が見やすくするためです。

${範囲名}はイシュー番号、チケット番号や日付、簡易説明などこのコメント範囲がどこからどこまでのものかを示すために設定します。
イシュー番号、チケット番号がお勧めです。トラッカー上により詳細な経緯を記載する事ができるからです。

${詳細説明}は文字通り「この範囲をなぜ修正したのか」を示すために記載します。
状況によっては省略可能です。

コメント範囲の開始宣言

2行目の//まで含めて範囲の開始宣言です。
これは「ここから下はコメント範囲である」事を明示するためです。
実際のコメントアウト・修正は3行目から行います。

//// STA ${範囲名} ${詳細説明}
//

コメント範囲の終了宣言

1行目の//まで含めて範囲の開始宣言です。
これは「ここから上はコメント範囲である」事を明示するためです。
実際の修正・コメントアウトは1行目の上まで続きます。

//
//// END ${範囲名}

コメント範囲内のインデントレベル

コメント範囲内にインデントが効いていて、コメントアウトするコードがある場合、行頭に単行コメントを設置し、もとのインデントを維持します。
元に戻す事を容易にすることと、grep時に意図をもって残している箇所である事を明確にするためです。

単行コメントの後に更に何らかのインデントを付けるかどうかは、文化圏によりけりです。
ここの例では1SP追加しています。

// function old_code()
// {
//     return 'old_code';
// }

実例

$codeに代入する関数、old_code()をnew_code()に変更する。

//// STA #6190 新コード発行機検証のため 2018/10/20に検証を終了し元に戻す
//
// $code = old_code()
$code = new_code();
//
//// END #6190