Documentação de programação funcional [fechado

Question

Existe alguma documentação padrão (como a UML para OO) para linguagens funcionais? Depois de baixar o Couch DB, que está escrito em Erlang e, olhando para o código -fonte, fiquei chocado, dificilmente há uma linha de documentação. Não há necessidade de documentar como todas essas funções dependem uma da outra? Existem melhores projetos de tamanho médio documentados também disponíveis gratuitamente, como as coisas são feitas usando esse paradigma?

Answer 1

O código deve ser documentado, independentemente da linguagem.

Parece haver um Estilo de documentação padrão chamado EDOC. O EDOC é capaz de produzir documentação externa da API; Citando de uma fonte:

O EDOC é o aplicativo padrão do Erlang para documentar a API Erlang diretamente dentro do código Erlang.

Isso é referenciado no Seção de documentação em erlang.org:

O EDOC permite escrever a documentação de um programa Erlang como comentários no próprio código -fonte, usando tags no formulário "@Name ...". Um arquivo de origem não precisa conter tags para o EDOC gerar sua documentação, mas sem tags o resultado conterá apenas as informações básicas disponíveis que podem ser extraídas do módulo.

UMA Pesquisa do Google focada Vou levá -lo daqui.

Answer 2

Em idiomas funcionais como Haskell ou ML, que têm tipos e talvez tipos de módulos (chamados "assinaturas" no ML padrão), os tipos fornecem uma grande documentação. Em idiomas funcionais como o esquema, que não têm tipos verificados pelo compilador, eles usam "contratos" - exceto quando são desleixados.

Erlang foi desenvolvido na Ericsson, e a indústria de telecomunicações tem uma cultura e um registro muito fortes de testes. Não me surpreenderia se a documentação de como essas funções deveriam funcionar em uma suíte de teste em algum lugar.

Resumo: As duas coisas mais próximas de um padrão são tipos (para linguagens funcionais com sistemas de tipo estático) e contratos (para linguagens funcionais que não possuem sistemas de tipos estáticos).

Answer 3

Este é um problema muito interessante!

Existem dois problemas - o primeiro está comentando o código e escrevendo alguma documentação (em um formulário textual). Isso deve ser feito da maneira usual, como nos idiomas OO. Você apenas escreveria uma visão geral de todos os módulos, funções e tipos que você usa em seu projeto. Em F# (uma linguagem funcional para .NET), você pode escrever comentários XML de maneira bastante semelhante à F# e gerar documentação a partir desses comentários. Eu acredito no F# documentação No MSDN, é gerado automaticamente a partir desses comentários. Aqui está um exemplo do código -fonte F# (se você instalar f# para vs 2008, ele também instalará o código -fonte das bibliotecas principais, o que pode ser um recurso interessante):

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

A segunda coisa que você mencionou é a UML - não há padrão para desenhar diagramas para linguagens funcionais. Este parece ser um problema complicado. No entanto, é certamente possível criar diagrama para código que usa alguma biblioteca específica. Muitas bibliotecas funcionais permitem compor código compondo várias funções simples. O processamento da lista é um bom exemplo:

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

Isso pode ser bem representado visualmente desenhando o fluxo de dados:

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

Desenhos semelhantes podem ser feitos para muitas bibliotecas funcionais e parecem ser bastante úteis (é o tipo de coisa que você desenha ao discutir algo ao quadro branco). No entanto, até onde eu sei, não há ferramentas para fazer isso automaticamente (embora deva ser possível IMHO).