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

25

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?

Tom Squires
fonte
7
"uma vez que geralmente são compostas por funções auto-descritivas menores". - isso não é, em princípio, diferente em linguagens imperativas. Mesmo assim, muitas vezes não está claro imediatamente o que a função grande fará no final: sempre se pode deduzi-la do próprio código, mas se isso levar muito mais tempo do que ler um comentário, você deve fornecer um.
leftaroundabout
2
Discordo. Desde langages funcionais não têm efeitos colaterais que você sabe exatamente o que ele vai fazer no final, retornar um valor com a assinatura dada
Tom Squires
8
nem todas as linguagens funcionais são puras, algumas têm efeitos colaterais.
Thanos Papathanasiou
1
Mas comente o que você sente em comentar ... Isso é um pensamento
excessivo
1
Seu projeto corre o risco de ter outros membros que não estão familiarizados com linguagens funcionais? Eles podem precisar de ajuda extra.
JeffO 18/11

Respostas:

84

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.

Sean McMillan
fonte
1
Ótima resposta, me mata ver o código repleto de comentários que explicam o quê e como (o que é evidente no próprio código), mas deixando-me adivinhar o porquê.
Eric Wilson
32
e isso é verdade independentemente do paradigma
jk.
2
Provavelmente isso é óbvio, mas você também deve adicionar comentários sobre o que e como, no caso de o código ser complicado ou complicado e exigir essa explicação. Obviamente, códigos como esse provavelmente também devem ser evitados, mas isso nem sempre é possível.
user606723
3
Embora essa resposta seja muito simples e a simplicidade tenha muito valor, ela não é totalmente verdadeira. Um nome de função geralmente não descreve e não pode descrever "o quê" em detalhes suficientes; portanto, é frequentemente necessária documentação (por exemplo, para descrever casos extremos). A documentação é frequentemente inserida nos comentários.
luiscubal
2
Indiscutivelmente, o nome da função também deve explicar por que está fazendo isso - quando é possível.
Yam Marcovic 23/11
14

Definitivamente, 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
Ingo
fonte
8
vovô sempre me diz para documentar o porquê em vez do quê. Então, eu usaria a última versão para o código imperativo também.
Simon Bergot
3
Seu avô está certo. Eu só queria demonstrar que certos comentários que fazem sentido no domínio imperativo são absolutamente inúteis no funcional.
Ingo
11

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.

Joh
fonte
Um bom argumento. Especialmente se o leitor estiver usando alguma biblioteca compilada e puder ver apenas assinaturas de funções expostas e seus comentários. Eles nunca verão as entranhas auto-descritivas do seu código.
FrustratedWithFormsDesigner
3

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.

Heinzi
fonte
2

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.

perdian
fonte
1

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.

dan_waterworth
fonte
0

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.

Michael Riley - também conhecido por Gunny
fonte