Si dovrebbe commentare diversamente nei linguaggi funzionali? [chiuso]

Sto appena iniziando con la programmazione funzionale e mi chiedo il modo corretto di commentare il mio codice.

Sembra un po 'ridondante commentare una funzione breve poiché i nomi e la firma dovrebbero già dirti tutto ciò che devi sapere. Anche commentare funzioni più grandi sembra un po 'ridondante poiché sono generalmente composte da funzioni autodescrittive più piccole.

Qual è il modo corretto di commentare un programma funzionale? Dovrei usare lo stesso approccio della programmazione iterativa?

Il nome della funzione dovrebbe dire cosa stai facendo.

L'implementazione ti dirà come lo stai facendo.

Usa i commenti per spiegare perché lo stai facendo.

C'è sicuramente è un punto a questa domanda, come programmi funzionali di solito sono su un livello di astrazione diverso rispetto a quelli imperativi.

Per questo motivo, è necessario un altro stile di documentazione. Nei programmi iterativi un commento può essere utile come nel seguente codice, poiché l'essenza del codice è nascosta dietro il bollettino:

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

Ma questa è chiaramente una sciocchezza in un linguaggio funzionale:

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

Meglio:

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

Il motivo per cui documentiamo una funzione è che i lettori non vogliono o non possono leggere il corpo della funzione. Per questo motivo, si dovrebbero documentare grandi funzioni, anche in linguaggi funzionali. Non importa se è facile capire cosa fa la funzione osservandone l'implementazione.

Le funzioni devono essere commentate se il nome della funzione e i nomi dei parametri da soli non sono sufficienti per specificare il contratto .

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

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

In breve, il contratto definisce ciò che la funzione si aspetta e ciò che garantisce. A rigor di termini, se GetEmployeeListrestituisce un elenco ordinato ma non lo dice nel nome della funzione o nel commento, un consumatore di questa funzione non deve fare affidamento su questo comportamento. È un dettaglio dell'implementazione non documentato e l'autore di GetEmployeeListha la libertà di modificare questo comportamento in qualsiasi momento.

Il commento stesso non dovrebbe contenere una descrizione alternativa a ciò che fa il codice (che in realtà è espresso dal codice stesso), ma piuttosto una spiegazione dei motivi per cui il codice è scritto così com'è.

Detto questo, non vedo alcun motivo per cui un commento debba essere di per sé diverso in un linguaggio funzionale.

Adotto lo stesso approccio per documentare tutto il mio codice:

• Usa nomi descrittivi,
• Aggiungi commenti prima di qualsiasi logica ragionevolmente complicata se la logica complicata non può essere evitata,
• Scrivi una panoramica di tutto il sistema,

Se il nome e la firma del tipo non ti dicono esattamente cosa fa la funzione, di solito la stai facendo male.

A 25 anni tendi a ricordare le cose molto meglio. Man mano che invecchi e sei coinvolto in più sistemi con codice legacy (sì, il codice che scrivi oggi sarà un codice legacy tra 10-15 anni) può essere molto utile se ci sono commenti.