Czy należy komentować inaczej w językach funkcjonalnych? [Zamknięte]

25

Zaczynam dopiero od programowania funkcjonalnego i zastanawiam się, jak skomentować mój kod.

Komentowanie krótkiej funkcji wydaje się trochę zbędne, ponieważ nazwy i podpis powinny już powiedzieć ci wszystko, co musisz wiedzieć. Komentowanie większych funkcji również wydaje się nieco zbędne, ponieważ na ogół składają się one z mniejszych funkcji samoopisujących.

Jaki jest właściwy sposób komentowania programu funkcjonalnego? Czy powinienem stosować to samo podejście, co w programowaniu iteracyjnym?

functional-programming comments Tom Squires
źródło
7
„ponieważ na ogół składają się one z mniejszych funkcji opisowych”. - w zasadzie nie różni się to w imperatywnych językach. Nadal często nie jest od razu jasne, co ostatecznie zrobi duża funkcja: zawsze można wywnioskować to z samego kodu, ale jeśli zajmuje to znacznie więcej czasu niż przeczytanie komentarza, należy go podać.
lewo około
2
Nie zgadzam się. Ponieważ języki funkcjonalne nie wywołują skutków ubocznych, wiesz dokładnie, co ostatecznie zrobi, zwróć wartość z podanym podpisem
Tom Squires,
8
nie wszystkie języki funkcjonalne są czyste, niektóre mają skutki uboczne.
Thanos Papathanasiou,
1
Ale skomentuj to, co chcesz skomentować ... To jest przemyślenie
gd1
1
Czy w twoim projekcie istnieje ryzyko, że inni członkowie nie będą znali języków funkcjonalnych? Mogą potrzebować dodatkowej pomocy.
JeffO

Odpowiedzi:

84

Nazwa funkcji powinna powiedzieć, co robisz.

Wdrożenie powie Ci, jak to robisz.

Użyj komentarzy, aby wyjaśnić, dlaczego to robisz.

Sean McMillan
źródło
1
Świetna odpowiedź, zabija mnie widok kodu wypełnionego komentarzami wyjaśniającymi co i jak (co wynika z samego kodu), ale pozwalającym zgadywać, dlaczego.
Eric Wilson,
32
i jest to prawdą niezależnie od paradygmatu
jk.
2
Prawdopodobnie jest to oczywiste, ale należy również dodać komentarze na temat tego, co i jak w przypadku, gdy kod jest skomplikowany lub skomplikowany i wymaga takiego wyjaśnienia. Oczywiście tego rodzaju kodu i tak należy prawdopodobnie unikać, ale nie zawsze jest to możliwe.
user606723,
3
Chociaż ta odpowiedź jest bardzo prosta, a prostota ma dużą wartość, nie jest do końca prawdą. Nazwa funkcji często nie opisuje i nie może wystarczająco dokładnie opisać „co”, dlatego często konieczna jest dokumentacja (np. Opisanie przypadków skrajnych). Dokumentacja jest często wstawiana w komentarzach.
luiscubal
2
Prawdopodobnie nazwa funkcji powinna również wyjaśniać, dlaczego to robi - kiedy jest to możliwe.
Yam Marcovic,
14

Z pewnością pytanie ma sens, ponieważ programy funkcjonalne zwykle mają inny poziom abstrakcji niż programy imperatywne.

Z tego powodu potrzebny jest inny styl dokumentacji. W programach iteracyjnych komentarz może być pomocny, podobnie jak w poniższym kodzie, ponieważ jego istota jest ukryta za płytą kotłową:

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

Ale jest to oczywiście nonsens w funkcjonalnym języku:

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

Lepszy:

-- we need the FooBars in all uppercase for the Frobnitz-Interface
let result = map toUpperCase list
Ingo
źródło
8
dziadek zawsze każe mi dokumentować dlaczego zamiast tego. Więc użyłbym również ostatniej wersji kodu imperatywnego.
Simon Bergot,
3
Twój dziadek ma rację. Chciałem tylko wykazać, że niektóre komentarze, które mają jednak sens w imperatywnym obszarze, są absolutnie bezużyteczne w funkcjach.
Ingo
11

Dokumentujemy funkcję dlatego, że czytelnicy nie chcą lub nie mogą odczytać treści funkcji. Z tego powodu należy dokumentować duże funkcje, nawet w językach funkcjonalnych. Nie ma znaczenia, czy łatwo jest zrozumieć, co robi funkcja, patrząc na jej implementację.

Joh
źródło
Dobra uwaga. Zwłaszcza jeśli czytelnik korzysta z skompilowanej biblioteki i widzi tylko odsłonięte sygnatury funkcji i ich komentarze. Nigdy nie zobaczą opisów twojego kodu.
FrustratedWithFormsDesigner
3

Funkcje należy komentować, jeśli sama nazwa funkcji i nazwa parametru nie wystarczą do określenia kontraktu .

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

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

Krótko mówiąc, umowa określa, czego oczekuje funkcja i co gwarantuje. Ściśle mówiąc, jeśli GetEmployeeListzwraca posortowaną listę, ale nie mówi tego ani w nazwie funkcji, ani w komentarzu, konsument tej funkcji nie może polegać na tym zachowaniu. Jest to nieudokumentowany szczegół implementacji, a autor GetEmployeeListma swobodę zmiany tego zachowania w dowolnym momencie.

Heinzi
źródło
2

Sam komentarz nie powinien zawierać alternatywnego opisu tego, co robi kod (który tak naprawdę jest wyrażony przez sam kod), ale raczej wyjaśnienie powodów, dla których kod jest napisany tak, jak jest.

To powiedziawszy, nie widzę żadnego powodu, dlaczego komentarz powinien per se być różny w języku funkcjonalnym.

perdian
źródło
1

Stosuję to samo podejście do dokumentowania całego mojego kodu:

  • Używaj opisowych nazw,
  • Dodaj komentarze przed jakąkolwiek dość skomplikowaną logiką, jeśli nie można uniknąć skomplikowanej logiki,
  • Napisz przegląd całego systemu,

Jeśli nazwa i podpis typu nie mówią dokładnie, co robi funkcja, zwykle robisz to źle.

dan_waterworth
źródło
0

W wieku 25 lat pamiętasz rzeczy o wiele lepiej. W miarę starzenia się i korzystania z wielu systemów ze starszym kodem (tak, kod, który dziś piszesz, będzie starszym kodem za 10-15 lat), może być bardzo pomocny, jeśli pojawią się komentarze.

Michael Riley - AKA Gunny
źródło