为什么要在注释中声明 PHP 变量类型？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/7861375/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Why declare PHP variable type in a comment?
提问by stefmikhail
I'm fairly new to PHP, and I just started using NetBeans to develop my PHP code.
我对 PHP 还很陌生，我刚刚开始使用 NetBeans 来开发我的 PHP 代码。
Out of the blue, as I entered a variable in a query, a dialog popped up and asked me to complete a comment to hold the variable type. I did some investigation and found that this seems to be a popular feature of NetBeans, but I couldn't find any information to explain to me whythis was the case.
出乎意料的是，当我在查询中输入一个变量时，会弹出一个对话框并要求我完成注释以保存变量类型。我做了一些调查，发现这似乎是 NetBeans 的一个流行功能，但我找不到任何信息来向我解释为什么会这样。
Why would someone want to place a PHP variable's type in a comment? Is it for development use, or does it actually benefit the code itself? Is it integral, or optional?
为什么有人要在注释中放置 PHP 变量的类型？它是用于开发用途，还是实际上有益于代码本身？它是不可或缺的，还是可选的？
回答by Jonathan Spooner
Adding the type in a @vartag inside your method's comment will allow NetBeans to show you code completion. This of course is optional but it is always a good idea to fully document your code.
在@var方法注释内的标记中添加类型将允许 NetBeans 向您显示代码完成情况。这当然是可选的，但完整记录您的代码总是一个好主意。
Edit:A tip for NetBeans to auto-generate the comments for you is to use the /**expansion. To do this, simply place the cursor above the property or method you want to document and type /**and then press the ENTERkey. This will expand a phpDoc style comment and add the appropriate tags.
编辑：NetBeans 为您自动生成注释的一个技巧是使用/**扩展。为此，只需将光标放在要记录和键入的属性或方法上方/**，然后按ENTER键。这将展开一个 phpDoc 样式的注释并添加适当的标签。
Edit 2:You can use the @vartag on a property and you can use the @paramtag on a method to achieve the same effect with parameters passed into a method.
编辑 2：您可以@var在属性上使用标记，也可以@param在方法上使用标记来实现与传递给方法的参数相同的效果。
Use of the @vartag on a property will give you code hints while using the property any where it is visible:
@var在属性上使用标记将为您提供代码提示，同时在任何可见的地方使用该属性：
/**
*
* @var My_Type
*/
private $_myProperty;
Use of the @paramtag on a method will give you code hints while using the parameter inside the method:
@param在方法上使用标记会在使用方法内的参数时为您提供代码提示：
/**
*
* @param My_Type $obj
*/
public function myMethod($obj) {
}
Another way to achieve a similar effect while also providing a modicum of type safety is to use PHP's type hintingmechanism:
另一种实现类似效果同时还提供一点类型安全的方法是使用 PHP 的类型提示机制：
public function myMethod(My_Type $obj) {
}
Notice that this method has the type specified in the method signature. NetBeans will now provide the same code completion inside the method that is available using the @paramtag and PHP will produce a E_RECOVERABLE_ERRORif the type passed into the method is not the same type that was specified. See PHP's documentation regarding errorsand how to handle them if your interested in learning more about the above error.
请注意，此方法具有方法签名中指定的类型。NetBeans 现在将在使用@param标记的方法内提供相同的代码完成，E_RECOVERABLE_ERROR如果传递给方法的类型与指定的类型不同，PHP 将生成。如果您有兴趣了解有关上述错误的更多信息，请参阅PHP 关于错误以及如何处理它们的文档。
回答by Crozin
I guess you're talking about something like that:
我猜你在谈论这样的事情：
/**
* @var SimpleXMLElement $xml
*/
private $xml;
This is so called phpDoc comment. It allows you to generate API documentation (like this one for instance). Furthermore, most IDEs including Eclipse and NetBeans also support that syntax, and provide dynamic code completion etc.
这就是所谓的phpDoc 注释。它允许您生成 API 文档（例如这个文档）。此外，包括 Eclipse 和 NetBeans 在内的大多数 IDE 也支持该语法，并提供动态代码完成等。
回答by Kat
If you want to declare the type of a variable in the case where the variable is not a class property but just a variable that holds some returned value, use single star comments followed by @var followed by your variable name and finally followed by the type of that variable. For example:
如果您想在变量不是类属性而只是保存某些返回值的变量的情况下声明变量的类型，请使用单星注释，后跟 @var 后跟变量名，最后后跟类型那个变量。例如：
/* @var $errorMessage NotificationMessage */
$errorMessage= $allMessages->rewind()->current();
will tell NetBeans or PhpStorm that $errorMessage is an instance of NotificationMessage, and you should get the code completion for that variable.
将告诉 NetBeans 或 PhpStorm $errorMessage 是 NotificationMessage 的一个实例，您应该获得该变量的代码完成。
回答by venimus
Despite netbeans use it for autocompletion it is often useful for documenting your code:
尽管 netbeans 将它用于自动完成，但它通常对记录您的代码很有用：
In this case you know what this method gets and what it returns but inside the code you have no idea what is happening
在这种情况下，你知道这个方法得到什么以及它返回什么，但在代码中你不知道发生了什么
/**
* Returns some stuff
* @param string $someObj
* @return array
*/
public function someMethod($someObj) {
$factoredObj = getObject($someObj); //you are not sure what type it returns
$resultArray = $factoredObj->toArray();
return $resultArray;
}
You can comment it with /* @var $variable type */inside the code
您可以/* @var $variable type */在代码内部对其进行注释
/**
* Returns some stuff
* @param string $someObj
* @return array
*/
public function someMethod($someObj) {
/* @var $factoredObj someType */
$factoredObj = getObject($someObj);
$resultArray = $factoredObj->toArray();
return $resultArray;
}
or
或者
$factoredObj = getObject($someObj); /* @var $factoredObj someType */
回答by Len
Because PHP is a loose/duck typed language, when you create a large program those type hints can help you or others understand what is going on if an issue should arise. For example, expecting a mixed type and sending an integer.
因为 PHP 是一种松散/鸭子类型的语言，所以当您创建一个大型程序时，这些类型提示可以帮助您或其他人在出现问题时了解发生了什么。例如，期望混合类型并发送整数。
