功能性编程文档

Question

是否有像面向对象的UML一样的标准文档适用于函数式语言？ 下载了用Erlang编写的CouchDB并查看源代码后，我感到震惊，几乎没有一行文档。 这些函数之间的依赖关系不需要记录吗？ 是否有更好的中等规模项目可供免费学习，以了解如何使用这种范例？

- stacker

Answer 1

在像Haskell或ML这样具有类型和模块类型（在标准ML中称为“签名”）的函数式语言中，类型提供了大量的文档。在像Scheme这样没有由编译器检查类型的函数式语言中，它们使用“合同”代替 - 除非它们很随意。

Erlang是在Ericsson开发的，电信行业具有非常强的文化和测试记录。如果这些函数应该如何工作的文档在某个测试套件中，那就不足为奇了。

总结：对于具有静态类型系统的函数式语言，最接近标准的是类型；对于没有静态类型系统的函数式语言，最接近标准的是合同。

- Norman Ramsey

---

当然，还有John Hughes的QuickCheck（最初是为Haskell设计的，现在是Erlang的商业产品）。 - Jörg W Mittag

Answer 2

无论使用哪种语言，代码都应该有文档记录。

似乎有一个名为EDoc的标准文档风格。 EDoc能够生成外部API文档; 引用一种来源:

EDoc是Erlang标准应用程序，可在Erlang代码中直接记录Erlang API。

这在erlang.org的文档部分中被引用：

EDoc允许您将Erlang程序的文档编写为源代码中的注释，使用形式为“@Name ...”的标记。源文件不必包含EDoc的标记即可生成其文档，但是如果没有标记，则结果将仅包含可以从模块中提取的基本可用信息。

一个专注的 Google 搜索将带您离开这里。

- Adam Matan

---

感谢提供 process-one 的链接。IM 客户端项目 ejabbered 是我正在寻找的：http://www.process-one.net/en/wiki/ejabberd_module_development/ - stacker

Answer 3

这是一个非常有趣的问题！

有两个问题 - 第一个是对代码进行注释并编写一些文档（以文本形式）。这应该像OO语言中那样进行。您只需编写有关项目中使用的所有模块、函数和类型的概述即可。在F#（一种用于.NET的函数式语言）中，您可以以与F#类似的方式编写XML注释，并从这些注释生成文档。我相信MSDN上的F#文档是从这些注释自动生成的。以下是来自F#源代码的示例（如果您安装了VS 2008的F#，它还将安装核心库的源代码，这可能是一个有趣的资源）：

/// Return the first element of the list.
///
/// Raises <c>System.ArgumentException</c> if <c>list</c> is empty
val head: list:'T list -> 'T

你提到的第二件事是UML——对于函数式语言，没有绘制图表的标准。这似乎是一个棘手的问题。然而，为使用某个特定库的代码创建图表是完全可能的。许多函数库允许你通过组合几个简单函数来组合代码。列表处理是一个很好的例子：

let custNames = customers |> List.map (fun customer -> customer.Name) 
let empNames = employees |> List.map (fun employee -> employee.Name) 
let result = List.concat [custNames; empNames]

这可以通过绘制数据流来进行视觉呈现：

+-----------+    +-----+
| customers |--->| map |\
+-----------+    +-----+ \ +--------+   +--------+
                          >| concat |-->| result |
+-----------+    +-----+ / +--------+   +--------+
| employees |--->| map |/
+-----------+    +-----+

类似的图表可以用于许多功能库，它们似乎非常有用（当您在白板上讨论某些事情时，这是您绘制的类型）。然而，据我所知，目前没有自动完成此操作的工具（尽管我认为这应该是可能的）。

- Tomas Petricek