是否真的需要执行以下操作:
/**
* ...
*
* @return void
*/
我有很多没有返回值的方法,在注释中放入类似的内容似乎真的很多余。遗漏它会被认为是不好的形式吗?
是否真的需要执行以下操作:
/**
* ...
*
* @return void
*/
我有很多没有返回值的方法,在注释中放入类似的内容似乎真的很多余。遗漏它会被认为是不好的形式吗?
Answers:
如果明确说明了文档,则将其保留,但这不是绝对必要的。这是一个完全主观的决定。
就个人而言,我会忽略它。
编辑
我站纠正。稍作搜索后,维基百科页面显示:
@return [类型描述]此标记不应用于使用void返回类型定义的构造函数或方法。
phpdoc.org网站说:
@return数据类型描述
@return数据类型1 |数据类型2描述@return标记用于记录函数或方法的返回值。@returns是@return的别名,以支持其他自动记录器的标签格式
数据类型应该是有效的PHP类型(int,string,bool等),返回的对象类型的类名或简单地“混合”。如果要显式显示多种可能的返回类型,请使用竖线将它们列出,并用空格分隔(例如“ @return int | string”)。如果在@return标记中将类名用作数据类型,则phpDocumentor将自动创建指向该类文档的链接。此外,如果函数返回多个可能的值,请使用|将它们分开。字符,并且phpDocumentor将解析出返回值中的所有类名称。phpDocumentor将显示未修改的可选描述。
如此...基于此,我想说的是排除空白。至少这是非标准的。
return
值的函数和方法,这里可以省略@return标记,在这种情况下,意味着@return void。”
@return void
。
void
自PHP 7.1起,该类型是有效的返回类型,根据下面的答案,如@tivnet所述,根据phpDocumentor,它也是phpDocs的有效类型。
根据phpDocumentor,@return void是有效的:
http://www.phpdoc.org/docs/latest/guides/types.html#keywords
...该类型通常仅在定义方法或函数的返回类型时使用。基本定义是,用此类型指示的元素不包含值,并且用户不应依赖任何检索到的值。
例如:
/** * @return void */ function outputHello() { echo 'Hello world'; }
在上面的示例中,未指定return语句,因此未确定返回值。
来源:http : //www.phpdoc.org/docs/latest/for-users/phpdoc/types.html(存档页面)。
由于最近学到的东西,我必须编辑答案。
使用@return void
代替@return null
具有非常特殊的含义,请考虑以下两个PHP代码示例。
<?php
/**
* @return void
*/
function return_never() {
echo "foo";
}
/**
* @return null|string
*/
function return_sometimes() {
if ($this->condition()) {
return "foo";
}
}
在第一个示例中,PHP实际上将返回NULL
,因为PHP总是返回NULL
。但是,返回值对于调用方没有用,因为它没有说明函数的功能。IDE可以使用的文档化信息@return void
来指示开发人员使用了返回值,但没有任何作用。
<?php
$foo1 = return_never();
$foo2 = return_sometimes();
第一次调用是没有意义的,因为变量将始终包含NULL
,第二次调用实际上可能包含某些内容。如果将函数调用置于条件中,这将变得更加有趣。
<?php
if (($foo1 = return_never())) {
// Dead code
var_dump($foo1);
}
if (($foo2 = return_sometimes())) {
var_dump($foo2);
}
如你看到的, @return void
有其用例,应该在适用的情况下使用。
还要注意,它将成为即将到来的PHP PSR-5标准的一部分。[1]
null
。我对吗?我认为,那@returns void
是最好的选择。
NULL
如果您不返回任何其他内容,则函数将始终返回。使用exit()
或类似函数的函数仍会返回,NULL
但您不会收到它,因为PHP会直接跳转到关闭阶段,而忽略您的代码。
finally
在我致电时运行块exit
。两者之间没有直接的关联,但是感觉并不正确。感谢您的启发。:)
NULL
[…]”。我想我们可以exit
通过简单地告诉PHP停止执行当前代码并直接跳到关闭阶段,而忽略此后的任何代码,从而与goto进行比较(因此goto嵌套在比任何当前函数嵌套的更广泛的作用域[global]中) 。甲最后块不被执行,但许多其它功能(例如register_shutdown
,__destruct
)。
@returns void
来指示该函数终止整个脚本执行,例如在HTTP重定向中。同样,最好使用它来指示该函数未设计为返回任何内容。
从php 7.1开始,void
是有效的返回类型,可以在函数上强制执行。
我会一直将其添加到文档块中。
编写它的另一个好处是,由于疏忽void
而使方法与可能返回任何内容但@return
在文档块上没有条目的方法区分开。
这是我理解和使用PhpDocumentor批注的方式:
<?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();
}
就我个人而言,我认为最大的不足是记录函数返回非常重要。当前标准没有关于永不返回的函数的任何文档。...因此,返回void表示该函数确实返回了。
考虑这个代码块
<?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()
}
显然,使用@return至少表明该函数确实返回了
void
并将其放入docs中的方法签名中。