Si dovrebbe commentare in modo diverso nelle lingue funzionali? [chiuso]

Il nome della funzione dovrebbe dire cosa stai facendo.

L'implementazione ti dirà come stai facendo.

Utilizza i commenti per spiegare perché lo stai facendo.

Sicuramente è un punto in questa domanda, poiché i programmi funzionali di solito si trovano su un livello di astrazione diverso da quelli imperativi.

Per questo motivo è necessario un altro stile di documentazione. Nei programmi iterativi un commento può essere d'aiuto come nel codice seguente, perché l'essenza del codice è nascosta dietro lo standard:

// 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 questo è chiaramente un non senso 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 osservando la sua implementazione.

Le funzioni dovrebbero 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 poche parole, il contratto definisce ciò che la funzione si aspetta e ciò che garantisce. In senso stretto, se GetEmployeeList restituisce una lista ordinata 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 di implementazione non documentato e l'autore di GetEmployeeList ha 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 perché il codice è scritto così com'è.

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

Ho lo stesso approccio per documentare tutto il mio codice:

• Utilizza nomi descrittivi,
• Aggiungi commenti prima di qualsiasi logica ragionevolmente complicata se non è possibile evitare una logica complicata,
• Scrivi una panoramica dell'intero sistema,

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

All'età di 25 anni tendi a ricordare le cose molto meglio. Invecchiando e partecipando a più sistemi con codice legacy (sì, il codice che scrivi oggi sarà un codice legacy in 10-15 anni) può essere molto utile se ci sono commenti.