Funktionelle Programmierdokumentation [geschlossen

Question

Gibt es Standarddokumentation (wie UML für OO) für funktionale Sprachen? Nach dem Herunterladen von Couch DB, das in Erlang geschrieben wurde und den Quellcode betrachtet habe, war ich schockiert, es gibt kaum eine Dokumentationslinie. Gibt es keine Notwendigkeit zu dokumentieren, wie all diese Funktionen voneinander abhängen? Gibt es besser dokumentierte mittelgroße Projekte, die auch frei verfügbar sind, wie es mit diesem Paradigma fertig ist?

Answer 1

Der Code sollte unabhängig von der Sprache dokumentiert werden.

Es scheint eine zu geben Standard -Dokumentationsstil namens EDOC. EDOC kann eine externe API -Dokumentation erstellen; Zitat aus einer Quelle:

EDOC ist die Erlang -Standardanwendung, um die Erlang -API direkt im Erlang -Code zu dokumentieren.

Dies wird in der verwiesen Dokumentationsabschnitt unter erlang.org:

Mit Edoc können Sie die Dokumentation eines Erlang -Programms als Kommentare im Quellcode selbst schreiben, indem Sie Tags auf dem Formular "@Name ..." verwenden. Eine Quelldatei muss keine Tags für EDOC enthalten, um ihre Dokumentation zu generieren. Ohne Tags enthält das Ergebnis jedoch nur die grundlegenden verfügbaren Informationen, die aus dem Modul extrahiert werden können.

EIN Fokussierte Google -Suche Ich werde dich von hier aus nehmen.

Answer 2

In funktionalen Sprachen wie Haskell oder ML, die Typen und möglicherweise Modultypen (in Standard -ML genannt "" Signaturen "haben), bieten die Typen eine große Dokumentation. In funktionalen Sprachen wie Schema, bei denen die Typen nicht vom Compiler überprüft werden, verwenden sie stattdessen "Verträge" - außer wenn sie schlampig sind.

Erlang wurde in Ericsson entwickelt, und die Telekommunikationsindustrie hat eine sehr starke Kultur und Aufzeichnungen über Tests. Es würde mich nicht überraschen, wenn die Dokumentation, wie diese Funktionen funktionieren sollen, irgendwo in einer Testsuite erfolgen sollen.

Zusammenfassung: Die beiden nächsten Dinge zu einem Standard sind Typen (für funktionale Sprachen mit statischen Typsystemen) und Verträge (für funktionale Sprachen, die keine statischen Typsysteme haben).

Answer 3

Dies ist ein sehr interessantes Problem!

Es gibt zwei Probleme - das erste kommentiert den Code und schreibt eine Dokumentation (in Textform). Dies sollte auf die übliche Weise wie in OO -Sprachen erfolgen. Sie schreiben nur einen Überblick über alle Module, Funktionen und Typen, die Sie in Ihrem Projekt verwenden. In F# (eine funktionale Sprache für .NET) können Sie XML -Kommentare auf ziemlich ähnliche Weise wie in F# schreiben und aus diesen Kommentaren Dokumentation generieren. Ich glaube das F# Dokumentation auf MSDN wird automatisch aus diesen Kommentaren generiert. Hier ist ein Beispiel aus F# Quellcode (wenn Sie F# für VS 2008 installieren, installiert er auch den Quellcode der Kernbibliotheken, was eine interessante Ressource sein könnte):

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

Das zweite, was Sie erwähnt haben, ist UML - es gibt keinen Standard für das Zeichnen von Diagrammen für funktionale Sprachen. Dies scheint ein schwieriges Problem zu sein. Es ist jedoch sicherlich möglich, ein Diagramm für Code zu erstellen, der eine bestimmte Bibliothek verwendet. Viele funktionale Bibliotheken ermöglichen es Ihnen, Code zu komponieren, indem Sie mehrere einfache Funktionen komponieren. Die Listenverarbeitung ist ein gutes Beispiel:

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

Dies könnte gut visuell dargestellt werden, indem der Datenfluss gezogen wird:

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

Ähnliche Zeichnungen können für viele funktionale Bibliotheken durchgeführt werden, und sie scheinen ziemlich nützlich zu sein (es ist die Art von Dingen, die Sie zeichnen, wenn Sie etwas am Whiteboard diskutieren). Soweit ich weiß, gibt es jedoch keine Werkzeuge, um dies automatisch zu tun (obwohl es möglich sein sollte, imho zu sein).