動的タイピング言語のドキュメント

Question

簡単な質問：どのような関数パラメータや戻り値を動的言語で記述するのが最適な方法ですか？各関数定義の後にコメントを追加しますか？

Answer 1

表記規則は、言語の静的/動的な入力の性質よりも、言語の注釈/文書化機能に依存します。多くの場合、1つの言語に対して複数の異なるドキュメントツールが存在するため、使用されるドキュメントツールに依存します。静的型付き言語では、技術的な型のパラメータを文書化する必要はありませんが、その意味と目的を文書化する必要があります。

C由来の構文を持つ言語の大きなグループは、Javadocスタイルのコメントを使用します。 PHPでの例：

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

私は全体的に推測し、これは最も主流のスタイルです：

は

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

Ruby用YARDツールは、同様の規則を使用しています。

いくつかの言語では、パラメータのリストを文書化する必要があるときに箇条書きリストなどを使用して自由形式のコメントを書きます。この点で興味深い例は、そのポッドのコメントではPerlです：raluによって提供されている例に

=item stuff(radius) 

Calculates the area of circle. 

=cut 

sub stuff { 

反して、私はそれが関数定義の前に文書を持っているより一般的だと思う...しかし、最終的にそれはすべての依存します言葉に

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ヘルプ機能で使用されます。