一个人在功能语言上应该有不同的评论吗？[关闭]

我才刚刚开始函数式编程，我想知道注释我的代码的正确方法。

注释一个简短的函数似乎有点多余，因为名称和签名已经可以告诉您所有您需要知道的内容。注释较大的函数似乎也有些多余，因为它们通常由较小的自描述函数组成。

注释功能程序的正确方法是什么？我应该使用与迭代编程相同的方法吗？

函数名称应该说什么你在干什么。

该实现将告诉您您的操作方式。

使用注释来解释为什么你这样做。

这个问题肯定有一个要点，因为功能程序通常与命令式程序处于不同的抽象级别。

因此，需要另一种文档样式。在迭代程序中，注释可能会像下面的代码一样有帮助，因为代码的本质隐藏在样板后面：

// map 'toUpperCase' over 'container' yielding 'result'
Container result = new Container();
for (int i=0; i < container.size(); i++) { 
             result.addToTail(container.atElement(i).toUpperCase());
}

但这显然是功能语言中的废话：

-- map 'toUpperCase' over 'list'
let result = map toUpperCase list

更好：

-- we need the FooBars in all uppercase for the Frobnitz-Interface
let result = map toUpperCase list

我们记录功能的原因是读者不希望或无法阅读功能的主体。因此，即使使用功能语言，也应记录大型功能。通过查看其实现是否容易理解该函数的功能并不重要。

如果仅函数名称和参数名称不足以指定合同，则应对函数进行注释。

// returns a list of Employees    <-- not necessary
def GetEmployeeList: ...

// returns a list of Employees sorted by last name    <-- necessary
def GetEmployeeList: ...

简而言之，合同定义了功能期望和保证的功能。严格来说，如果GetEmployeeList返回排序列表，但在函数名称或注释中均未返回，则此函数的使用者一定不能依赖此行为。这是一个未记录的实现细节，其作者GetEmployeeList可以随时更改此行为。

注释本身不应包含对代码功能的替代性描述（实际上是由代码本身表达的），而是对按其原样编写代码的原因的解释。

就是说，我看不出在功能语言中注释本身应该有所不同的任何原因。

我采用相同的方法来记录所有代码：

• 使用描述性名称，
• 如果无法避免复杂逻辑，请在任何合理复杂逻辑之前添加注释，
• 撰写整个系统的概述，

如果名称和类型签名没有确切告诉您函数的功能，则通常是错误的。

25岁时，您的记忆力会更好。随着年龄的增长，您将涉及具有遗留代码的多个系统（是的，今天编写的代码将在10到15年内成为遗留代码），如果有注释，它将非常有帮助。