/**
* Calculates the area of circle.
* @param float $radius The radius of circe.
* @return float The area
*/
function area($radius) {
Ruby 的 YARD 工具使用类似的约定：
# Calculates the area of circle.
# @param [Number] radius The radius of circe.
# @return [Number] The area
def area(radius)
我想总体来说，这是最主流的风格。
在多种语言中，当您需要记录参数列表时，您只需编写几乎自由格式的注释，使用项目符号列表等。这方面的一个有趣的例子是 Perl 及其 pod 注释：与
=item stuff(radius)
Calculates the area of circle.
=cut
sub stuff {
ralu 提供的示例相反，我认为在函数定义之前有文档更常见......但最终这一切都取决于语言。
The conventions depend more on commenting/documentation features of the language than on the static/dynamic typing nature of the language. Even more do they depend on the documentation tool used, as often multiple different documentation tools exist for one language. Although in statically typed languages you don't have to document the technical types of the parameters, you still need to document the meaning and purpose.
A large group of languages with C-derived syntax use Javadoc style comments. For example in PHP:
/**
* Calculates the area of circle.
* @param float $radius The radius of circe.
* @return float The area
*/
function area($radius) {
The YARD tool for Ruby uses a similar convention:
# Calculates the area of circle.
# @param [Number] radius The radius of circe.
# @return [Number] The area
def area(radius)
I guess on the whole, this is the most mainstream style.
In several languages you just write pretty much free-form comments, using bulleted lists etc when you need to document list of parameters. An interesting example in this regard is Perl with its pod comments:
=item stuff(radius)
Calculates the area of circle.
=cut
sub stuff {
Contrary to the examples provided by ralu, I think it's more common to have documentation before the function definition... but in the end it all depends on the language.
发布评论
评论（2）
这些约定更多地取决于语言的注释/文档功能，而不是语言的静态/动态类型性质。它们更依赖于所使用的文档工具，因为一种语言通常存在多种不同的文档工具。尽管在静态类型语言中，您不必记录参数的技术类型，但仍然需要记录其含义和用途。
大量具有 C 派生语法的语言使用 Javadoc 样式注释。例如在 PHP 中：
Ruby 的 YARD 工具使用类似的约定：
我想总体来说，这是最主流的风格。
在多种语言中，当您需要记录参数列表时，您只需编写几乎自由格式的注释，使用项目符号列表等。这方面的一个有趣的例子是 Perl 及其 pod 注释：与
ralu 提供的示例相反，我认为在函数定义之前有文档更常见......但最终这一切都取决于语言。
The conventions depend more on commenting/documentation features of the language than on the static/dynamic typing nature of the language. Even more do they depend on the documentation tool used, as often multiple different documentation tools exist for one language. Although in statically typed languages you don't have to document the technical types of the parameters, you still need to document the meaning and purpose.
A large group of languages with C-derived syntax use Javadoc style comments. For example in PHP:
The YARD tool for Ruby uses a similar convention:
I guess on the whole, this is the most mainstream style.
In several languages you just write pretty much free-form comments, using bulleted lists etc when you need to document list of parameters. An interesting example in this regard is Perl with its pod comments:
Contrary to the examples provided by ralu, I think it's more common to have documentation before the function definition... but in the end it all depends on the language.
Python 在函数定义后使用注释，MATLAB 在函数定义后使用注释。
和Matlab
我不熟悉其他动态语言。这被认为是正确的注释约定，并且在两个示例中都使用了帮助函数。
Python uses comments after function definition and MATLAB uses comments after function definition.
and Matlab
I am not familiar whit other dynamic languages. This is considered proper commenting convention and is used whit help function in both examples.