真的有必要做这样的事情:
/**
* ...
*
* @return void
*/
我有很多没有返回值的方法,在评论中放这样的东西似乎真的是多余的。将其排除在外会被认为是不好的形式吗?
真的有必要做这样的事情:
/**
* ...
*
* @return void
*/
我有很多没有返回值的方法,在评论中放这样的东西似乎真的是多余的。将其排除在外会被认为是不好的形式吗?
如果它使文档清楚,则将其保留,但这不是绝对必要的。这是一个完全主观的决定。
就个人而言,我会把它排除在外。
编辑
我的立场得到纠正。经过一番谷歌搜索,维基百科页面说:
@return [类型描述] 此标记不应用于定义为 void 返回类型的构造函数或方法。
phpdoc.org 网站说:
@return 数据类型描述
@return 数据类型1|数据类型2 描述@return 标签用于记录函数或方法的返回值。@returns 是 @return 的别名,用于支持其他自动文档的标签格式
数据类型应该是有效的 PHP 类型(int、string、bool 等)、返回对象类型的类名,或者简单地“混合”。如果您想显式显示多种可能的返回类型,请将它们以竖线分隔,不带空格(例如“@return int|string”)。如果在@return 标记中使用类名作为数据类型,phpDocumentor 将自动创建指向该类文档的链接。此外,如果函数返回多个可能的值,请使用 | 分隔它们。字符,并且 phpDocumentor 将解析出返回值中的任何类名。phpDocumentor 将显示未修改的可选描述。
Sooo...基于此,我会说离开空白。至少,它是非标准的。
根据 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]
从 php 7.1 开始,void
它是有效的返回类型,可以在函数上强制执行。
我总是将它添加到文档块中。
编写它的另一个好处是将方法与可能返回任何内容但由于疏忽而在 docblock 上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 的使用至少表明该函数确实返回