如何在动态类型语言中描述函数参数？

Question

我的问题更多面向Python，但也可能是关于JavaScript或其他脚本语言。

我通常使用静态类型语言（Java，C++，ActionScript，...）进行开发。

我喜欢不时使用Python，而且我还需要有时使用JavaScript。这些是动态类型语言。没有什么不对，但我通常有很多头痛的问题来了解函数或方法中需要哪些参数。它发生，即使它是我自己的代码与一些docstrings！也许是因为眼睛不得不在功能的定义中寻找其他位置。

当然，答案应该在文档中。但有时并不清楚所有，或因为使用鸭的键入文档本身可以是很难写（“第一个参数是必须有一个庸医（）方法和羽毛（ARG）方法，其中一个功能arg是一个字符串“）。我非常喜欢的是在语言本身内部的一种参数描述（即使它是单独的，就像ActionScript一样）。

明确描述函数/方法参数的最佳实践是什么？

如何创建一个特殊的装饰器（如果使用Python），其目的是检查数据类型，当我们使用它（但因为它将在运行时使用，而不是在写入时间，无论如何将是点）？

你认为这不应该是一个问题吗？做比当前的文档字符串更多会混淆开发人员，或者我的思想太静态输入导向？

Answer 1

我不知道有关JavaScript，但Python有可选function annotations自3版本，它看起来像：

def haul(item: Haulable, *vargs: PackAnimal) -> Distance: 

或：

def compile(source: "something compilable", 
      filename: "where the compilable thing comes from", 
      mode: "is this a single statement or a suite?"): 

看到the PEP以获取更多信息。

它们可以在运行时访问，甚至可以用于type checking。

Answer 2

为什么鸭打字使得文档很难写？

当你编写一个函数时，假设参数是一个特定类型的参数或者确认一个特定的接口来编写函数......所以只需记录它。

例如，如果你有一个swim_in_pond(duck)方法，没有必要记录“duck预计将有quack()，swim()和dive()方法” - 在大多数情况下，这是完全足够的说“duck是Duck实例”。或者，如果你记录了“Duck样”的界面是非常重要的，我发现它有利于声明基类作为文档：

class DuckBase(object): 
    def quack(self): 
     """ Makes the duck quack. """ 

    def swim(self): 
     """ Swims around. 
      Assumes the duck is already in water. 
      Updates the duck's position. """ 

    def dive(self): 
     """ Dives either as deep as possible (either until the duck runs out of 
      air, or it hits the bottom of the pond). """