Documentación de programación funcional

Question

¿Existe alguna documentación estándar (como UML para OO) para idiomas funcionales? Después de descargar couch db, que está escrito en erlang y mirando el código fuente, quedé impresionado, apenas hay una línea de documentación. ¿No hay necesidad de documentar cómo todas estas funciones dependen unas de otras? ¿Hay proyectos de tamaño mediano mejor documentados disponibles gratuitamente también, aprenda, cómo se hacen las cosas utilizando este paradigma?

Answer 1

El código debe documentarse, independientemente del idioma.

Parece que hay standard documentation style called EDoc. EDoc puede producir documentación API externa; citando de una fuente:

edoc es la aplicación Erlang estándar para documentar la API Erlang directamente dentro del código Erlang.

Esto se hace referencia en el documentation section at erlang.org:

edoc le permite escribir la documentación de un programa de Erlang como comentarios en el código fuente en sí, el uso de etiquetas en la forma "@Name .. . ". Un archivo de origen no tiene que contener etiquetas para edoc para generar su documentación, pero sin las etiquetas el resultado sólo contendrá el básico información disponible que se puede extraer de el módulo.

A focused Google search lo llevará desde aquí.

Answer 2

En idiomas funcionales como Haskell o ML, que tienen tipos y tal vez tipos de módulos (llamados "firmas" en ML estándar), los tipos proporcionan una gran cantidad de documentación. En lenguajes funcionales como Scheme, que no tienen tipos verificados por el compilador, usan "contratos" en su lugar — excepto cuando son descuidados.

Erlang se desarrolló en Ericsson, y la industria de las telecomunicaciones tiene una cultura muy fuerte y un historial de pruebas. No me sorprendería que la documentación de cómo se supone que funcionen esas funciones esté en un banco de pruebas en alguna parte.

Resumen: las dos cosas más cercanas a un estándar son tipos (para lenguajes funcionales con sistemas de tipo estático) y contratos (para lenguajes funcionales que no cuentan con sistemas de tipo estático).

Answer 3

¡Este es un problema muy interesante!

Hay dos problemas: el primero es comentar el código y escribir cierta documentación (en forma de texto). Esto debe hacerse de la manera habitual como en los lenguajes OO. Simplemente escribiría una descripción general de todos los módulos, funciones y tipos que usa en su proyecto. En F # (un lenguaje funcional para .NET), puede escribir comentarios XML de una manera bastante similar a F # y generar documentación a partir de estos comentarios. Creo que el F# documentation en MSDN se genera automáticamente a partir de estos comentarios.Este es un ejemplo de C# código fuente (si se instala F # para VS 2008, también se instala el código fuente de bibliotecas del núcleo, lo que podría ser un recurso interesante):

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

La segunda cosa que usted ha mencionado es UML - no hay un estándar para dibujar diagramas para lenguajes funcionales. Esto parece ser un problema complicado. Sin embargo, es ciertamente posible crear un diagrama para el código que usa una biblioteca específica. Muchas bibliotecas funcionales le permiten componer código al componer varias funciones simples. Se crea la lista es un buen ejemplo:

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

Esto podría ser muy bien representado visualmente trazando el flujo de datos:

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

dibujos similares pueden realizarse por muchas bibliotecas funcionales y que parecen ser bastante útil (es el tipo de cosa que dibujas cuando discutes algo en la pizarra). Sin embargo, hasta donde sé, no hay herramientas para hacerlo automáticamente (aunque debería ser posible en mi humilde opinión).