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?
functional-programming
comments
Tom Squires
fonte
fonte
Respostas:
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.
fonte
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ê:
Mas isso é claramente absurdo em uma linguagem funcional:
Melhor:
fonte
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.
fonte
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 .
Em poucas palavras, o contrato define o que a função espera e o que garante. A rigor, se
GetEmployeeList
retorna 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 deGetEmployeeList
tem a liberdade de alterar esse comportamento a qualquer momento.fonte
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.
fonte
Eu adoto a mesma abordagem para documentar todo o meu código:
Se o nome e a assinatura do tipo não informam exatamente o que a função faz, você geralmente está fazendo errado.
fonte
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.
fonte