Faut-il commenter différemment dans les langages fonctionnels? [fermé]

Je commence tout juste la programmation fonctionnelle et je me demande comment corriger mon code.

Il semble un peu redondant de commenter une fonction courte car les noms et la signature devraient déjà vous dire tout ce que vous devez savoir. Commenter des fonctions plus grandes semble également un peu redondant car elles sont généralement composées de fonctions auto-descriptives plus petites.

Quelle est la bonne façon de commenter un programme fonctionnel? Dois-je utiliser la même approche que dans la programmation itérative?

Le nom de la fonction doit indiquer ce que vous faites.

L'implémentation vous dira comment vous le faites.

Utilisez des commentaires pour expliquer pourquoi vous le faites.

Il certainement est un point dans cette question, car les programmes fonctionnels sont généralement à un niveau d'abstraction différent que les impératifs.

Pour cette raison, un autre style de documentation est nécessaire. Dans les programmes itératifs, un commentaire peut être utile comme dans le code suivant, car l'essence du code est cachée derrière le passe-partout:

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

Mais c'est clairement un non-sens dans un langage fonctionnel:

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

Mieux:

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

La raison pour laquelle nous documentons une fonction est que les lecteurs ne veulent pas ou ne peuvent pas lire le corps de la fonction. Pour cette raison, il faut documenter les grandes fonctions, même dans les langages fonctionnels. Peu importe s'il est facile de comprendre ce que fait la fonction en examinant son implémentation.

Les fonctions doivent être commentées, si le nom de la fonction et les noms des paramètres ne suffisent pas à eux seuls à spécifier le contrat .

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

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

En un mot, le contrat définit ce que la fonction attend et ce qu'elle garantit. À strictement parler, si GetEmployeeListrenvoie une liste triée mais ne le dit ni dans le nom de la fonction ni dans le commentaire, un consommateur de cette fonction ne doit pas se fier à ce comportement. Il s'agit d'un détail d'implémentation non documenté, et l'auteur de GetEmployeeLista la liberté de modifier ce comportement à tout moment.

Le commentaire lui-même ne doit pas contenir une description alternative à ce que fait le code (qui est en fait exprimée par le code lui-même), mais plutôt une explication des raisons pour lesquelles le code est écrit tel qu'il est.

Cela dit, je ne vois aucune raison pour laquelle un commentaire devrait être différent en soi dans un langage fonctionnel.

J'utilise la même approche pour documenter tout mon code:

• Utilisez des noms descriptifs,
• Ajoutez des commentaires avant toute logique raisonnablement compliquée si une logique compliquée ne peut être évitée,
• Rédiger un aperçu de l'ensemble du système,

Si le nom et la signature de type ne vous disent pas exactement ce que fait la fonction, vous vous trompez généralement.

À 25 ans, vous vous souvenez beaucoup mieux des choses. À mesure que vous vieillissez et que vous êtes impliqué dans plusieurs systèmes avec du code hérité (oui, le code que vous écrivez aujourd'hui sera du code hérité dans 10 à 15 ans), il peut être très utile s'il y a des commentaires.