动态类型语言的文档

Question

一个简单的问题：哪种方法可以记录动态语言中的函数参数类型或返回值？在每个函数定义后添加注释？

Answer 1

Python在函数定义之后使用注释，MATLAB在函数定义之后使用注释。

def fibo_gen(): 
    '''Generate Fibonacci numbers; return an iterator''' 
    x, y = 0, 1 
    while True: 
       yield x 
       x, y = y, x + y

和Matlab

function addtwo(x,y)
%  addtwo(x,y)  Adds two numbers, vectors, whatever, and
%               print the result = x + y
x+y

我不熟悉其他动态语言。这被认为是正确的评论约定，并且在两个示例中都使用了whit帮助功能。

Answer 2

这些约定更多地取决于语言的注释/文档功能，而不是语言的静态/动态类型性质。他们更依赖于所使用的文档工具，因为一种语言通常存在多种不同的文档工具。虽然在静态类型语言中，您不必记录参数的技术类型，但仍需要记录其含义和目的。

使用C派生语法的大量语言使用Javadoc样式注释。例如在PHP中：

/**
 * 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提供的示例相反，我认为在函数定义之前使用文档更为常见......但最终都取决于语言。