Deve-se comentar de maneira diferente nas linguagens funcionais? [fechadas]

Estou apenas começando com a programação funcional e estou pensando sobre a maneira correta de comentar meu código.

Parece um pouco redundante comentar uma função curta, pois os nomes e assinaturas já devem lhe dizer tudo o que você precisa saber. Comentar funções maiores também parece um pouco redundante, pois geralmente são compostas por funções auto-descritivas menores.

Qual é a maneira correta de comentar um programa funcional? Devo usar a mesma abordagem que na programação iterativa?

O nome da função deve dizer o que você está fazendo.

A implementação mostrará como você está fazendo isso.

Use comentários para explicar por que você está fazendo isso.

Definitivamente, há um ponto nesta questão, pois os programas funcionais geralmente estão em um nível de abstração diferente dos imperativos.

Por isso, é necessário outro estilo de documentação. Em programas iterativos, um comentário pode ser útil, como no código a seguir, porque a essência do código está oculta por trás do clichê:

// map 'toUpperCase' over 'container' yielding 'result'
Container result = new Container();
for (int i=0; i < container.size(); i++) { 
             result.addToTail(container.atElement(i).toUpperCase());
}

Mas isso é claramente absurdo em uma linguagem funcional:

-- map 'toUpperCase' over 'list'
let result = map toUpperCase list

Melhor:

-- we need the FooBars in all uppercase for the Frobnitz-Interface
let result = map toUpperCase list

A razão pela qual documentamos uma função é que os leitores não querem ou não podem ler o corpo da função. Por esse motivo, deve-se documentar grandes funções, mesmo em linguagens funcionais. Não importa se é fácil entender o que a função faz, observando sua implementação.

As funções devem ser comentadas, se o nome da função e os nomes dos parâmetros por si só não forem suficientes para especificar o contrato .

// returns a list of Employees    <-- not necessary
def GetEmployeeList: ...

// returns a list of Employees sorted by last name    <-- necessary
def GetEmployeeList: ...

Em poucas palavras, o contrato define o que a função espera e o que garante. A rigor, se GetEmployeeListretorna uma lista classificada, mas não o diz no nome da função nem no comentário, o consumidor dessa função não deve confiar nesse comportamento. É um detalhe de implementação não documentado e o autor de GetEmployeeListtem a liberdade de alterar esse comportamento a qualquer momento.

O comentário em si não deve conter uma descrição alternativa ao que o código faz (que na verdade é expresso pelo próprio código), mas uma explicação das razões pelas quais o código foi escrito da maneira que é.

Dito isto, eu não vejo nenhuma razão para que um comentário deve per se ser diferente em uma linguagem funcional.

Eu adoto a mesma abordagem para documentar todo o meu código:

• Use nomes descritivos,
• Adicione comentários antes de qualquer lógica razoavelmente complicada se a lógica complicada não puder ser evitada,
• Escreva uma visão geral de todo o sistema,

Se o nome e a assinatura do tipo não informam exatamente o que a função faz, você geralmente está fazendo errado.

Aos 25 anos, você costuma se lembrar das coisas muito melhor. À medida que você envelhece e se envolve com vários sistemas com código legado (sim, o código que você escreve hoje será um código legado em 10 a 15 anos), pode ser muito útil se houver comentários.