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


25

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?


7
"car ils sont généralement composés de fonctions auto-descriptives plus petites." - ce n'est, en principe, pas différent dans les langues impératives. Pourtant, il n'est souvent pas immédiatement clair ce que la grande fonction fera à la fin: on pourrait toujours le déduire du code lui-même, mais si cela prend beaucoup plus de temps que de lire un commentaire, vous devez en fournir un.
partir du

2
Je ne suis pas d'accord. Étant donné que les langages fonctionnels n'ont pas d'effets secondaires, vous savez exactement ce qu'il fera à la fin, renvoyez une valeur avec la signature donnée
Tom Squires

8
tous les langages fonctionnels ne sont pas purs, certains ont des effets secondaires.
Thanos Papathanasiou

1
Mais commentez ce que vous ressentez pour commenter ... Ceci est surpensé
gd1

1
Votre projet court-il le risque d'avoir d'autres membres qui ne sont pas familiers avec les langages fonctionnels? Ils peuvent avoir besoin d'une aide supplémentaire.
JeffO

Réponses:


84

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.


1
Excellente réponse, cela me tue de voir du code jonché de commentaires qui expliquent le quoi et le comment (ce qui est évident dans le code lui-même) mais me laissant deviner le pourquoi.
Eric Wilson

32
et cela est vrai quel que soit le paradigme
jk.

2
Cela va probablement sans dire, mais vous devez également ajouter des commentaires sur quoi et comment dans le cas où le code est compliqué ou alambiqué et nécessite une telle explication. Bien sûr, un code comme celui-ci devrait également être évité de toute façon, mais ce n'est pas toujours possible.
user606723

3
Bien que cette réponse soit très simple et que la simplicité ait beaucoup de valeur, elle n'est pas entièrement vraie. Souvent, un nom de fonction ne décrit pas et ne peut pas décrire "quoi" de manière suffisamment détaillée, de sorte qu'une documentation est souvent nécessaire (par exemple pour décrire les cas marginaux). La documentation est fréquemment insérée dans les commentaires.
luiscubal

2
On peut dire que le nom de la fonction devrait également expliquer pourquoi elle le fait - quand c'est possible.
Yam Marcovic

14

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

8
grand-père me dit toujours de documenter le pourquoi au lieu du quoi. J'utiliserais donc la dernière version pour le code impératif également.
Simon Bergot

3
Votre grand-père a raison. Je voulais juste démontrer que certains commentaires qui ont du sens néanmoins dans le domaine impératif sont absolument inutiles sur le plan fonctionnel.
Ingo

11

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.


Un bon point. Surtout si le lecteur utilise une bibliothèque compilée et ne peut voir que les signatures de fonction exposées et leurs commentaires. Ils ne verront jamais les tripes auto-descriptives de votre code.
FrustratedWithFormsDesigner

3

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.


2

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.


1

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.


0

À 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.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.