84

次のようなことをする必要がありますか？

/**
 * ...
 * 
 * @return void
 */

戻り値を持たないメソッドがかなりありますが、コメントにこのようなものを入れるのは本当に冗長に思えます。それを省略するのは悪い形と見なされますか?

4

6 に答える 6

92

ドキュメントで明確になっている場合はそのままにしておきますが、厳密には必要ありません。それは完全に主観的な決定です。

個人的には、私はそれを除外します。

編集
私は修正されたままです。少しグーグルした後、ウィキペディアのページには次のように書かれています：

@return [型の説明] このタグは、void 戻り型で定義されたコンストラクターまたはメソッドには使用しないでください。

phpdoc.org の Web サイトには次のように書かれています。

@return データ型の説明
@return データ型 1|データ型 2 の説明

@return タグは、関数またはメソッドの戻り値を文書化するために使用されます。@returns は、他の自動ドキュメンタのタグ形式をサポートする @return のエイリアスです

データ型は、有効な PHP 型(int、string、bool など)、返されるオブジェクトの型のクラス名、または単に "mixed" である必要があります。複数の可能な戻り値の型を明示的に表示したい場合は、それらをスペースなしでパイプ区切りでリストします (例: "@return int|string")。クラス名が @return タグのデータ型として使用されている場合、phpDocumentor はそのクラスのドキュメントへのリンクを自動的に作成します。さらに、関数が複数の可能な値を返す場合は、| を使用してそれらを区切ります。文字であり、phpDocumentor は戻り値のクラス名を解析します。phpDocumentor は、オプションの説明を変更せずに表示します。

すっごい… それを踏まえて、空欄は省きます。少なくとも非標準です。

于 2010-01-14T01:11:36.647 に答える
15

最近学んだことから、回答を編集する必要があります。

@return voidの代わりに使用することに@return nullは非常に特別な意味があります。次の 2 つの PHP コードの例を考えてみましょう。

<?php

/**
 * @return void
 */
function return_never() {
    echo "foo";
}

/**
 * @return null|string
 */
function return_sometimes() {
    if ($this->condition()) {
        return "foo";
    }
}

NULL最初の例では、PHP は常に を返すため、PHP は実際にはを返しますNULL。しかし、戻り値は、関数が何をしたかについて何も言っていないので、呼び出し元には役に立ちません。IDE は、文書化された情報を@return void使用して、目的を果たさない戻り値が使用されていることを開発者に示すことができます。

<?php

$foo1 = return_never();

$foo2 = return_sometimes();

変数には常に が含まれているため、最初の呼び出しはNULL意味がありません。2 番目の呼び出しには実際に何かが含まれている可能性があります。関数呼び出しを条件式に入れると、これはさらに興味深いものになります。

<?php

if (($foo1 = return_never())) {
    // Dead code
    var_dump($foo1);
}

if (($foo2 = return_sometimes())) {
    var_dump($foo2);
}

ご覧のとおり、@return voidにはユース ケースがあり、該当する場合は使用する必要があります。

また、今後の PHP PSR-5 標準の一部になることにも注意してください。[1]

[1] http://www.php-fig.org/psr/

于 2013-08-24T17:26:39.813 に答える