Sollte man in funktionalen Sprachen anders kommentieren? [geschlossen]

25

Ich fange gerade erst mit der funktionalen Programmierung an und frage mich, wie ich meinen Code richtig kommentieren kann.

Es erscheint ein wenig überflüssig, eine kurze Funktion zu kommentieren, da die Namen und Unterschriften bereits alles enthalten sollten, was Sie wissen müssen. Das Kommentieren größerer Funktionen erscheint ebenfalls ein wenig überflüssig, da sie im Allgemeinen aus kleineren selbstbeschreibenden Funktionen bestehen.

Wie kann man ein Funktionsprogramm richtig kommentieren? Sollte ich den gleichen Ansatz wie bei der iterativen Programmierung verwenden?

Tom Squires
quelle
7
"Da sie im Allgemeinen aus kleineren selbstbeschreibenden Funktionen bestehen." - das ist im Prinzip nicht anders in imperativen Sprachen. Trotzdem ist oft nicht sofort klar, was die große Funktion letztendlich bewirken wird : Man kann sie immer aus dem Code selbst ableiten, aber wenn das erheblich länger dauert als das Lesen eines Kommentars, sollten Sie einen Kommentar eingeben.
Abfahrt um ca.
2
Ich stimme dir nicht zu. Da funktionale Sprachen keine Nebenwirkungen haben, wissen Sie genau, was sie am Ende bewirken werden. Geben Sie einen Wert mit der angegebenen Signatur zurück
Tom Squires,
8
Nicht alle funktionalen Sprachen sind rein, einige haben Nebenwirkungen.
Thanos Papathanasiou
1
Aber kommentiere, was du denkst, um zu kommentieren ... Dies ist overthink
gd1
1
Geht Ihr Projekt das Risiko ein, andere Mitglieder zu haben, die sich mit funktionalen Sprachen nicht auskennen? Sie benötigen möglicherweise zusätzliche Hilfe.
JeffO

Antworten:

84

Der Funktionsname sollte sagen, was Sie tun.

Die Implementierung zeigt Ihnen, wie Sie es tun.

Erkläre anhand von Kommentaren, warum du das tust.

Sean McMillan
quelle
1
Tolle Antwort, es macht mich fertig, Code mit Kommentaren zu sehen, die erklären, was und wie (was aus dem Code selbst hervorgeht), aber ich kann das Warum erraten.
Eric Wilson
32
und das ist unabhängig vom Paradigma wahr
jk.
2
Dies ist wahrscheinlich selbstverständlich, aber Sie sollten auch Kommentare hinzufügen, was und wie in dem Fall, dass der Code kompliziert oder kompliziert ist und eine solche Erklärung erfordert. Natürlich sollte Code wie dieser auch sowieso vermieden werden, aber das ist nicht immer möglich.
user606723
3
Obwohl diese Antwort sehr einfach ist und Einfachheit viel Wert hat, ist sie nicht ganz richtig. Ein Funktionsname kann und kann häufig nicht genau genug beschreiben, weshalb häufig eine Dokumentation erforderlich ist (z. B. zur Beschreibung von Randfällen). Die Dokumentation wird häufig in Kommentare eingefügt.
Luiscubal
2
Möglicherweise sollte der Funktionsname auch erklären, warum es so ist - wenn es möglich ist.
Yam Marcovic
14

Es auf jeden Fall ist ein Punkt in dieser Frage, als funktionalen Programme in der Regel auf einer anderen Abstraktionsebene als zwingend notwendig , diejenigen sind.

Aus diesem Grund ist ein anderer Dokumentationsstil erforderlich. In iterativen Programmen kann ein Kommentar hilfreich sein, wie im folgenden Code, da sich das Wesentliche des Codes hinter dem Boilerplate verbirgt:

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

Aber das ist eindeutig Unsinn in einer funktionalen Sprache:

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

Besser:

-- we need the FooBars in all uppercase for the Frobnitz-Interface
let result = map toUpperCase list
Ingo
quelle
8
Opa sagt mir immer, ich soll das Warum statt das Was dokumentieren. Daher würde ich die letzte Version auch für imperativen Code verwenden.
Simon Bergot
3
Dein Opa hat recht. Ich wollte nur zeigen, dass bestimmte Kommentare, die dennoch im Imperativbereich Sinn machen, in der Funktion absolut nutzlos sind.
Ingo
11

Der Grund, warum wir eine Funktion dokumentieren, ist, dass Leser den Funktionskörper nicht lesen wollen oder können. Aus diesem Grund sollte man große Funktionen auch in funktionalen Sprachen dokumentieren. Es spielt keine Rolle, ob es einfach ist, die Funktionsweise der Funktion anhand ihrer Implementierung zu verstehen.

Joh
quelle
Ein guter Punkt. Insbesondere, wenn der Leser eine kompilierte Bibliothek verwendet und nur offen gelegte Funktionssignaturen und deren Kommentare sehen kann. Sie werden nie die selbsterklärenden Eingeweide Ihres Codes sehen.
FrustratedWithFormsDesigner
3

Funktionen sollten kommentiert werden, wenn der Funktionsname und der Parametername alleine nicht ausreichen, um den Vertrag zu spezifizieren .

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

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

Kurz gesagt, der Vertrag definiert, was die Funktion erwartet und was sie garantiert. Streng genommen GetEmployeeListdarf sich ein Verbraucher dieser Funktion nicht auf dieses Verhalten verlassen , wenn er eine sortierte Liste zurückgibt, dies jedoch weder im Funktionsnamen noch im Kommentar sagt. Es ist ein undokumentiertes Implementierungsdetail, und der Autor von GetEmployeeListhat die Freiheit, dieses Verhalten jederzeit zu ändern.

Heinzi
quelle
2

Der Kommentar selbst sollte keine alternative Beschreibung zu der Funktionsweise des Codes enthalten (die tatsächlich durch den Code selbst ausgedrückt wird), sondern vielmehr eine Erläuterung der Gründe, warum der Code so geschrieben ist, wie er ist.

Trotzdem sehe ich keinen Grund, warum ein Kommentar in einer funktionalen Sprache per se anders sein sollte .

perdian
quelle
1

Ich gehe genauso vor, um meinen gesamten Code zu dokumentieren:

  • Verwenden Sie beschreibende Namen,
  • Fügen Sie Kommentare vor einer einigermaßen komplizierten Logik hinzu, wenn eine komplizierte Logik nicht vermieden werden kann.
  • Schreiben Sie einen Überblick über das gesamte System,

Wenn der Name und die Typunterschrift Ihnen nicht genau sagen, was die Funktion tut, machen Sie es normalerweise falsch.

dan_waterworth
quelle
0

Mit 25 erinnern Sie sich viel besser an Dinge. Wenn Sie älter werden und mit mehreren Systemen mit Legacy-Code arbeiten (ja, der Code, den Sie heute schreiben, wird in 10-15 Jahren Legacy-Code sein), kann es sehr hilfreich sein, wenn Kommentare vorhanden sind.

Michael Riley - AKA Gunny
quelle