PHPDoc: @return void notwendig?

Lesezeit: 7 Minuten

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 zu schreiben. Würde es als schlechte Form angesehen werden, es wegzulassen?

Benutzer-Avatar
Jonathan Finland

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

Ich persönlich würde es weglassen.

BEARBEITEN

Ich stehe korrigiert. Nach ein wenig googeln, die Wikipedia-Seite sagt:

@Rückkehr [type description] Dieses Etikett sollte nicht benutzt werden für Konstruktoren oder Methoden, die mit einem void-Rückgabetyp definiert sind.

Auf der Website phpdoc.org heißt es:

Beschreibung des @return-Datentyps
@return Datentyp1|Datentyp2 Beschreibung

Das Tag @return wird verwendet, um den Rückgabewert von Funktionen oder Methoden zu dokumentieren. @returns ist ein Alias ​​für @return, um Tag-Formate anderer automatischer Dokumentierer zu unterstützen

Der Datentyp sollte ein gültiger PHP-Typ sein (int, string, bool usw.), ein Klassenname für den Typ des zurückgegebenen Objekts oder einfach “gemischt”. Wenn Sie mehrere mögliche Rückgabetypen explizit anzeigen möchten, listen Sie sie durch Pipes getrennt 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 sie 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. Das ist zumindest nicht genormt.

  • Bringt das Hinzufügen überhaupt etwas? Ich glaube an PHPDoc, wenn Sie keinen Rückgabetyp dokumentieren, den es automatisch annimmt void und fügt es in die Methodensignatur in den Dokumenten ein.

    – Markus W

    14. Januar 2010 um 1:16 Uhr

  • @Marc W: siehe meine Bearbeitung. es ist nicht nur nicht notwendig, es soll auch nicht verwendet werden.

    – Jonathan Finland

    14. Januar 2010 um 1:33 Uhr

  • Könnte sich seit 2010 geändert haben, aber derzeit sagt phpdoc.org: “Funktionen und Methoden ohne a return Wert, das @return-Tag KANN hier weggelassen werden, in diesem Fall ist @return void impliziert.”

    – TFennis

    17. Dezember 2013 um 10:39 Uhr

  • @TFennis Danke. Ich werde das Legacy-Zitat so lassen, wie es ist, aber es scheint, dass phpdoc einfach toleranter ist, wie viele Entwickler es verwendet haben. Ich bemerke, dass die Wikipedia-Seite jetzt sagt [citation needed] für die Aussage zur Vermeidung @return void.

    – Jonathan Finland

    18. Dezember 2013 um 3:02 Uhr

  • Prüfen github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.mdvielleicht hat es sich aber irgendwann geändert @return void wird sogar in den Beispielen verwendet.

    – istepaniuk

    29. Januar 2021 um 17:34 Uhr

Benutzer-Avatar
tivnet

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 der Rückgabewert nicht bestimmt.

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

  • An dieser Stelle weise ich darauf hin, dass „dies die richtige Antwort ist“. 🙂

    – Tippfehler

    11. Oktober 2013 um 6:13 Uhr

  • Die richtige Antwort sollte in diese geändert werden.

    – BadHorsie

    10. Juli 2015 um 10:11 Uhr

  • In der Tat wäre dies die beste Antwort hier. Es ist auch Teil des kommenden 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

    – Kennzeichen

    6. Oktober 2015 um 9:33 Uhr

Benutzer-Avatar
Fleischfresser

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

Verwenden @return void Anstatt von @return null eine ganz besondere Bedeutung hat, 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ückkehren NULLda PHP immer zurückkehrt NULL. Der zurückgegebene Wert ist für den Aufrufer jedoch nutzlos, 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 ein Rückgabewert verwendet wird, der keinen Zweck erfüllt.

<?php

$foo1 = return_never();

$foo2 = return_sometimes();

Der erste Aufruf ist sinnlos, da die Variable immer enthält NULL, der zweite könnte tatsächlich etwas enthalten. Noch interessanter wird es, 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 du sehen kannst, @return void hat 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/

  • 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 void ist die beste Option.

    – Tamás Barta

    22. September 2014 um 13:22 Uhr

  • Eine Funktion wird immer zurückkehren NULL wenn Sie nichts anderes zurückgeben. Eine Funktion, die verwendet exit() oder so etwas kommt immer noch zurück NULL aber Sie erhalten es nicht, weil PHP direkt in die Shutdown-Phase springt und Ihren Code ignoriert.

    – Fleischfresser

    23. September 2014 um 9:19 Uhr


  • Interessant. Ich hätte angenommen, wenn das stimmt, was du sagst, finally Blöcke laufen, 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

    23. September 2014 um 12:33 Uhr

  • Eine bessere Formulierung wäre gewesen: „[…] würde trotzdem wiederkommen NULL […]“. Ich denke, wir können vergleichen exit mit goto, indem Sie PHP einfach mitteilen, die Ausführung des aktuellen Codes zu stoppen und direkt zur Shutdown-Phase zu springen, wobei von diesem Punkt an jeglicher Code ignoriert wird (also goto in einem äußereren Bereich [global] als jede aktuelle Funktion verschachtelt ist). Ein finally-Block wird nicht ausgeführt, aber viele andere Funktionen (z register_shutdown, __destruct).

    – Fleischfresser

    23. September 2014 um 13:12 Uhr


  • Das klingt sinnvoller, und das dachte ich auch zuerst. Ich habe mich auch für die Verwendung entschieden @returns void um anzuzeigen, dass die Funktion die gesamte Skriptausführung beendet, beispielsweise bei einer HTTP-Umleitung. Es wäre auch immer noch besser, es zu verwenden, um anzuzeigen, dass die Funktion nicht dafür ausgelegt ist, etwas zurückzugeben.

    – Tamás Barta

    23. September 2014 um 13:34 Uhr

Benutzer-Avatar
Dimitris Baltas

Ab PHP 7.1, void ist ein gültiger Rückgabetyp und kann einer Funktion erzwungen werden.

Ich würde stets füge es dem docblock hinzu.

Ein weiterer Vorteil des Schreibens besteht darin, die zu differenzieren void Methoden aus den Methoden, die alles zurückgeben können, aber keine haben @return Eintrag auf dem Docblock durch Fahrlässigkeit.

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();
}

Benutzer-Avatar
Narrim

Ich persönlich denke, dass die große Sache, die dabei fehlt, ist, dass es wichtig ist, eine Funktionsrückgabe überhaupt zu dokumentieren. Derzeit haben Standards keine Dokumentation für Funktionen, die niemals zurückkehren …. daher ist eine Rückgabe void eine Art 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 zumindest an, dass die Funktion zurückkehrt

1351660cookie-checkPHPDoc: @return void notwendig?

This website is using cookies to improve the user-friendliness. You agree by using the website further.

Privacy policy