¿Se debe comentar de manera diferente en lenguajes funcionales? [cerrado]

Recién estoy comenzando con la programación funcional y me pregunto sobre la forma correcta de comentar mi código.

Parece un poco redundante comentar una función corta ya que los nombres y la firma ya deberían decirle todo lo que necesita saber. Comentar funciones más grandes también parece un poco redundante, ya que generalmente se componen de funciones autodescriptivas más pequeñas.

¿Cuál es la forma correcta de comentar un programa funcional? ¿Debo usar el mismo enfoque que en la programación iterativa?

El nombre de la función debe decir lo que estás haciendo.

La implementación te dirá cómo lo estás haciendo.

Usa comentarios para explicar por qué lo estás haciendo.

Definitivamente hay un punto en esta pregunta, ya que los programas funcionales generalmente están en un nivel de abstracción diferente al de los imperativos.

Debido a esto, se necesita otro estilo de documentación. En los programas iterativos, un comentario puede ser útil, como en el siguiente código, porque la esencia del código está oculta detrás de repetitivo:

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

Pero esto es claramente una tontería en un lenguaje funcional:

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

Mejor:

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

La razón por la que documentamos una función es que los lectores no quieren o no pueden leer el cuerpo de la función. Por esta razón, uno debe documentar funciones grandes, incluso en lenguajes funcionales. No importa si es fácil entender lo que hace la función al observar su implementación.

Las funciones deben comentarse si el nombre de la función y los nombres de los parámetros por sí solos no son suficientes para especificar el contrato .

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

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

En pocas palabras, el contrato define lo que la función espera y lo que garantiza. Estrictamente hablando, si GetEmployeeListdevuelve una lista ordenada pero no lo dice ni en el nombre de la función ni en el comentario, un consumidor de esta función no debe confiar en este comportamiento. Es un detalle de implementación no documentado, y el autor de GetEmployeeListtiene la libertad de cambiar este comportamiento en cualquier momento.

El comentario en sí no debe contener una descripción alternativa de lo que hace el código (que en realidad lo expresa el propio código), sino más bien una explicación de las razones por las cuales el código está escrito de la manera en que está.

Dicho esto, yo no veo ninguna razón por la cual un comentario debe per se ser diferente en un lenguaje funcional.

Tomo el mismo enfoque para documentar todo mi código:

• Use nombres descriptivos,
• Agregue comentarios antes de cualquier lógica razonablemente complicada si no se puede evitar la lógica complicada,
• Escriba una descripción general de todo el sistema,

Si el nombre y la firma de tipo no le dicen exactamente qué hace la función, generalmente lo está haciendo mal.

A los 25 años tiendes a recordar las cosas mucho mejor. A medida que envejece y se involucra con múltiples sistemas con código heredado (sí, el código que escriba hoy será código heredado en 10-15 años) puede ser muy útil si hay comentarios.