动态类型语言中的文档

Question

一个简单的问题：哪种类型的函数参数或动态语言中的返回值的文档是最好的方法？在每个函数定义之后添加注释？

Answer 1

约定更多依赖于语言的评论/文档特征，而不是语言的静态/动态类型本质。更多的是依赖于使用的文档工具，因为一种语言通常存在多种不同的文档工具。尽管在静态类型语言中，您不必记录参数的技术类型，但仍需要记录其含义和用途。

一组具有C派生语法的语言使用Javadoc样式注释。例如，在PHP：

/** 
* Calculates the area of circle. 
* @param float $radius The radius of circe. 
* @return float The area 
*/ 
function area($radius) { 

Ruby的院子里工具使用类似的约定：

# Calculates the area of circle. 
# @param [Number] radius The radius of circe. 
# @return [Number] The area 
def area(radius) 

我想就整体而言，这是最主流风格。

在您需要记录参数列表时，您可以使用多种语言编写非常自由的注释，使用项目符号列表等。这方面的一个有趣的例子是Perl，以它的荚评论：

=item stuff(radius) 

Calculates the area of circle. 

=cut 

sub stuff { 

相反，由RALU提供的例子，我认为这是比较常见的有函数定义之前的文档......但最终这一切都取决于在语言上。

Answer 2

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帮助功能。