phpdocの@returnは付けるか、付けないか？

2016/05/16

PHP

仕事でphpdocの書き方で迷った箇所があったので、少々調べてみました。

調べた内容は「phpdocに@returnを付けるか、付けないか？」です。

調べて見ると色々な意見がありました。

3つの意見

@returnのことを調べてみると「stack over flow」の「PHPDoc: @return void necessary?」というスレッドに当たりました。

この中では3つの意見がありました。

返り値がない場合でも、@return voidとして返り値がないことを明示するべきである。

このように下記のようなコードの場合でも@returnを必ず付けて返り値がないことをphpdocに明示的にする派

/**
 * sample function
 * 
 * @return void
 */
function hoge(){
    echo "Hello world";
}

今度は@returnがないなら、返り値がないってことだからわざわざphpdocに書く必要はない

このように下記のようなコードの場合は@returnは不要派

/**
 * sample function
 */
function hoge(){
    echo "Hello world";
}

returnを使っている場合のみ付けるべきであるとありました。

下記のコードはreturn使用時のみ書くべきだとするコードです。

returnを使用しているので、PHPDOCにvoidと付けることになります。

/**
 * sample function
 *
 * @return void
 */
function hoge($arg){
    if(is_null($arg)){
        return;
    }

    echo "Hello world";
}

この問題が発生した現場ではvoidは暗示されているので、@returnに書かないってことで決定しました。

ちなみにphpDocumenterの@returnのページでもこれについて書かれているが、暗示されているので省略してもよいと書かれています。