Documentación de programación funcional [cerrado

Question

¿Hay alguna documentación estándar (como UML para OO) para lenguajes funcionales? Después de descargar Couch DB, que está escrito en Erlang y, al mirar el código fuente, me sorprendió, apenas hay una línea de documentación. ¿No hay necesidad de documentar cómo todas estas funciones dependen entre sí? ¿Hay mejores proyectos de tamaño mediano documentados disponibles gratuitamente para aprender, cómo se hacen las cosas usando este paradigma?

Answer 1

El código debe estar documentado, independientemente del lenguaje.

Parece haber un Estilo de documentación estándar llamado Edoc. EDOC puede producir documentación de API externa; citado de una fuente:

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

Esto se hace referencia en el Sección de documentación en erlang.org:

EdoC le permite escribir la documentación de un programa Erlang como comentarios en el código fuente en sí, utilizando etiquetas en el formulario "@name ...". Un archivo fuente no tiene que contener etiquetas para que EDOC genere su documentación, pero sin etiquetas el resultado solo contendrá la información básica disponible que se puede extraer del módulo.

A Search enfocada en Google te llevará desde aquí.

Answer 2

En lenguajes 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 esquema, que no tienen tipos verificados por el compilador, usan "contratos" en su lugar, excepto cuando son descuidados.

Erlang fue desarrollado en Ericsson, y la industria de las telecomunicaciones tiene una cultura y un registro de pruebas muy fuerte. No me sorprendería si la documentación de cómo se supone que funcionan esas funciones está en una suite de prueba en alguna parte.

Resumen: Las dos cosas más cercanas a un estándar son los tipos (para lenguajes funcionales con sistemas de tipo estático) y contratos (para lenguajes funcionales que no tienen 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 alguna documentación (en forma textual). Esto debe hacerse de la manera habitual como en los idiomas 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 la de F# y generar documentación a partir de estos comentarios. Creo que el F# Documentación En MSDN se genera automáticamente a partir de estos comentarios. Aquí hay un ejemplo del código fuente F# (si instala F# para VS 2008, también instalará el código fuente de las bibliotecas centrales, 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

Lo segundo que mencionó es UML: no hay diagramas de dibujo para idiomas funcionales. Esto parece ser un problema complicado. Sin embargo, ciertamente es posible crear un diagrama para el código que use alguna biblioteca específica. Muchas bibliotecas funcionales le permiten componer código componiendo varias funciones simples. El procesamiento de 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 estar muy bien representado visualmente dibujando el flujo de datos:

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

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