PHPDoc: @return void notwendig?

81

Ist es wirklich notwendig, so etwas zu tun:

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

Ich habe einige Methoden, die keinen Rückgabewert haben, und es scheint wirklich überflüssig, so etwas in den Kommentar aufzunehmen. Wäre es eine schlechte Form, es wegzulassen?

Richie Marquez
quelle

Antworten:

91

Wenn es für die Dokumentation klar ist, lassen Sie es in, aber es ist nicht unbedingt notwendig. Es ist eine völlig subjektive Entscheidung.

Persönlich würde ich es weglassen.

EDIT
Ich stehe korrigiert. Nach ein wenig googeln heißt es auf der Wikipedia-Seite :

@return [Typbeschreibung] Dieses Tag sollte nicht für Konstruktoren oder Methoden verwendet werden, die mit einem ungültigen Rückgabetyp definiert sind.

Auf der Website phpdoc.org heißt es:

Beschreibung
des Datentyps @return Beschreibung des Datentyps @ return1 | Beschreibung des Datentyps2

Das @ return-Tag wird verwendet, um den Rückgabewert von Funktionen oder Methoden zu dokumentieren. @returns ist ein Alias ​​für @return zur Unterstützung von Tag-Formaten anderer automatischer Dokumentatoren

Der Datentyp sollte ein gültiger PHP-Typ (int, string, bool usw.), ein Klassenname für den zurückgegebenen Objekttyp oder einfach "gemischt" sein. Wenn Sie mehrere mögliche Rückgabetypen explizit anzeigen möchten, listen Sie sie ohne Leerzeichen auf (z. B. "@return int | string"). Wenn ein Klassenname als Datentyp im @ return-Tag verwendet wird, erstellt phpDocumentor automatisch einen Link zur Dokumentation dieser Klasse. Wenn eine Funktion mehrere mögliche Werte zurückgibt, trennen Sie diese außerdem mit | Zeichen, und phpDocumentor analysiert alle Klassennamen im Rückgabewert. phpDocumentor zeigt die optionale Beschreibung unverändert an.

Sooo ... Basierend darauf würde ich sagen, lass die Leere weg. Zumindest ist es nicht Standard.

Jonathan Fingland
quelle
Tut das Hinzufügen überhaupt etwas? Ich glaube an PHPDoc, wenn Sie keinen Rückgabetyp dokumentieren, wird dieser automatisch angenommen voidund in die Methodensignatur in den Dokumenten eingefügt.
Marc W
@Marc W: siehe meine Bearbeitung. Es ist nicht nur nicht notwendig, es soll auch nicht verwendet werden.
Jonathan Fingland
2
Könnte sich seit 2010 geändert haben, aber derzeit sagt phpdoc.org: "Funktionen und Methoden ohne returnWert, das @ return-Tag kann hier weggelassen werden. In diesem Fall wird @return void impliziert."
TFennis
@TFennis Danke. Ich werde das alte Zitat unverändert lassen, aber es scheint, dass phpdoc einfach toleranter gegenüber der Anzahl der Entwickler ist, die es verwendet haben. Ich stelle fest, dass auf der Wikipedia-Seite jetzt [Zitieren erforderlich] für die Aussage über das Vermeiden steht @return void.
Jonathan Fingland
Aus meiner Sicht ist diese Antwort veraltet. Der Typ voidist seit PHP 7.1 ein gültiger Rückgabetyp und wie @tivnet in der Antwort unten zeigt, ist er laut phpDocumentor auch ein gültiger Typ für phpDocs.
Ernesto Allely
50

Laut phpDocumentor ist @return void gültig:

http://www.phpdoc.org/docs/latest/guides/types.html#keywords

... dieser Typ wird normalerweise nur verwendet, wenn der Rückgabetyp einer Methode oder Funktion definiert wird. Die grundlegende Definition ist, dass das mit diesem Typ angegebene Element keinen Wert enthält und der Benutzer sich nicht auf einen abgerufenen Wert verlassen sollte.

Zum Beispiel:

 /**
  * @return void
  */
 function outputHello()
 {
     echo 'Hello world';
 }

Im obigen Beispiel ist keine return-Anweisung angegeben und somit wird der Rückgabewert nicht bestimmt.

Quelle: http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html ( archivierte Seite ).

tivnet
quelle
4
Hier weise ich darauf hin, dass dies die richtige Antwort ist. :)
Tippfehler
3
Die richtige Antwort sollte darauf geändert werden.
BadHorsie
4
In der Tat wäre dies hier die beste Antwort. Es ist auch Teil des bevorstehenden PSR-5-Standards. Ich würde mit dem folgenden Ansatz für semantisch sinnvolle Programmierung gehen: dereuromark.de/2015/10/05/return-null-vs-return-void
Markieren Sie den
15

Ich muss meine Antwort aufgrund von etwas bearbeiten, das ich kürzlich gelernt habe.

Die Verwendung von @return voidanstelle von @return nullhat eine ganz besondere Bedeutung. Betrachten Sie die folgenden zwei Beispiele für PHP-Code.

<?php

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

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

Im ersten Beispiel wird PHP tatsächlich zurückgegeben NULL, da PHP immer zurückgibt NULL. Der zurückgegebene Wert ist für den Aufrufer jedoch nicht von Nutzen, da er nichts darüber aussagt, was die Funktion getan hat. IDEs können die dokumentierten Informationen von verwenden @return void, um dem Entwickler anzuzeigen, dass Rückgabewerte verwendet werden, die keinen Zweck erfüllen.

<?php

$foo1 = return_never();

$foo2 = return_sometimes();

Der erste Aufruf ist sinnlos, da die Variable immer enthält NULL, der zweite möglicherweise tatsächlich etwas. Dies wird noch interessanter, wenn wir die Funktionsaufrufe in eine Bedingung setzen.

<?php

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

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

Wie Sie sehen können, @return voidhat seine Anwendungsfälle und sollte gegebenenfalls verwendet werden.

Beachten Sie auch, dass es Teil des kommenden PHP PSR-5-Standards sein wird. [1]

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

Fleischwolf
quelle
Guter Punkt, aber wenn die Funktion beendet wird, bedeutet dies, dass sie nicht zurückkehrt null. Habe ich recht? Ich denke, in diesem Fall @returns voidist die beste Option.
Tamás Barta
Eine Funktion wird immer zurückgegeben, NULLwenn Sie nichts anderes zurückgeben. Eine Funktion, die exit()oder etwas Ähnliches verwendet, kehrt immer noch zurück, NULLaber Sie erhalten sie nicht, da PHP direkt in die Abschaltphase springt und Ihren Code ignoriert.
Fleischwolf
Interessant. Ich hätte angenommen, wenn das, was Sie sagen, wahr ist, werden finallyBlöcke ausgeführt, wenn ich anrufe exit. Keine direkte Korrelation zwischen den beiden, aber es fühlt sich nicht richtig an. Danke, dass du mich aufgeklärt hast. :)
Tamás Barta
Ein besserer Wortlaut wäre gewesen: „[…] würde immer noch zurückkehren NULL[…]“. Ich denke, wir können exitmit goto vergleichen, indem wir PHP einfach anweisen, die Ausführung des aktuellen Codes zu beenden und direkt in die Shutdown-Phase zu springen, wobei jeder Code von diesem Punkt an ignoriert wird (also goto in einem äußereren Bereich [global] als jede aktuelle Funktion verschachtelt ist). . Ein finally - Block wird nicht ausgeführt, sondern auch viele andere Funktionen (zB register_shutdown, __destruct).
Fleischwolf
Das klingt sinnvoller, und das habe ich mir zuerst gedacht. Ich habe mich auch dafür entschieden, @returns voidanzuzeigen, dass die Funktion die gesamte Skriptausführung beendet, beispielsweise bei einer HTTP-Umleitung. Es wäre auch immer noch besser zu verwenden, um anzuzeigen, dass die Funktion nicht dafür ausgelegt ist, etwas zurückzugeben.
Tamás Barta
7

Ab PHP 7.1 voidist ein gültiger Rückgabetyp und kann für eine Funktion erzwungen werden.

Ich würde es immer auf dem Docblock hinzufügen.

Ein weiterer Vorteil des Schreibens besteht darin, die voidMethoden von den Methoden zu unterscheiden, die möglicherweise alles zurückgeben, aber @returnfahrlässig keinen Eintrag im Dokumentblock haben.

Dimitris Baltas
quelle
3

So verstehe und verwende ich PhpDocumentor-Anmerkungen:

<?php

/**
 * This method always returns string.
 * @return string
 */
public function useCase1()
{
    return 'foo';
}

/**
 * This method returns 2 data types so list them both using pipeline separator.
 * @return string|false
 */
public function useCase2()
{
    if ($this->foo === 1) {
        return 'foo';
    }
    return false;
}

/**
 * This method performs some operation and does not return anything so no return
 * annotation is needed.
 */
public function useCase3()
{
    $this->doOperation();
    $this->doAnotherOperation();
}

/**
 * If condition passes method returns void. If condition does not pass it returns
 * nothing so I think that specifying the return annotation with void is in space. :)
 * @return void
 */
public function useCase4()
{
    if ($this->foo === 1) {
        $this->doOperation();
        return;
    }
    $this->doAnotherOperation();
}
Dejv
quelle
0

Persönlich denke ich, dass das große Problem dabei ist, dass es wichtig ist, die Rückgabe einer Funktion überhaupt zu dokumentieren. Derzeit haben Standards keine Dokumentation für Funktionen, die niemals zurückkehren. Daher ist eine Rückgabelücke eine Möglichkeit zu sagen, dass diese Funktion tatsächlich zurückkehrt.

Betrachten Sie diesen Codeblock

<?php

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

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

/**
* This function actually doesnt return at all - it kills the script
**/
function noreturn() {
     //do somthing then
     die(); //or exit()
}

Die Verwendung von @return zeigt eindeutig an, dass die Funktion zurückkehrt

Narrim
quelle