25

I'm just getting started with functional programming and I'm wondering about the correct way to comment my code.

It seems a little redundant to comment a short function as the names and signature already should tell you everything you need to know. Commenting larger functions also seems a little redundant since they are generally comprised of smaller self-descriptive functions.

What is the correct way to comment a functional program? Should I use the same approach as in iterative programming?

Improve this question
5
  • 7
    "since they are generally comprised of smaller self-descriptive functions." — that's, in principle, no different in imperative languages. Still it's often not immediately clear what the large function will do in the end: one could always deduce it from the code itself, but if that takes considerably more time than reading a comment you should provide one.
    – leftaroundabout
    Nov 17, 2011 at 11:30
  • 2
    I disagree. Since Functional langages dont have side effects you know exactly what it will do in the end, return a value with the given signature
    – Tom Squires
    Nov 17, 2011 at 11:37
  • 8
    not all functional languages are pure, some do have side effects.
    – Thanos Papathanasiou
    Nov 17, 2011 at 12:14
  • 1
    But comment what you feel to comment... This is overthink
    – gd1
    Nov 17, 2011 at 18:27
  • 1
    Does your project run the risk of having other members who are not familiar with functional languages? They may need some extra help.
    – JeffO
    Nov 18, 2011 at 4:12

7 Answers 7

Reset to default
84

The function name should say what you're doing.

The implementation will tell you how you're doing it.

Use comments to explain why you're doing it.

Improve this answer
12
  • 1
    Great answer, it kills me to see code littered with comments that explain the what and how (which is evident from the code itself) but leaving me to guess the why.
    – Eric Wilson
    Nov 17, 2011 at 14:39
  • 32
    and this is true regardless of paradigm
    – jk.
    Nov 17, 2011 at 14:48
  • 2
    This probably goes without saying, but you should also add comments about what and how in the case that the code is complicated or convoluted and requires such explanation. Of course, code like this should also probably avoided anyways, but that's not always possible.
    – user606723
    Nov 17, 2011 at 17:33
  • 3
    While this answer is very simple and simplicity does have a lot of value, it is not entirely true. A function name often does not and can not describe "what" in sufficient detail, so documentation is often necessary(e.g. to describe edge cases). Documentation is frequently inserted in comments.
    – luiscubal
    Nov 17, 2011 at 19:22
  • 2
    Arguably, the function name should also explain why it's doing it - when it's possible.
    – Yam Marcovic
    Nov 23, 2011 at 17:50
14

There definitely is a point in this question, as functional programs usually are on a different abstraction level than imperative ones.

Because of this, another style of documentation is needed. In iterative programs a comment may be helpful like in the following code, because the essence of the code is hidden behind boilerplate:

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

But this is clearly nonsense in a functional language:

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

Better:

-- we need the FooBars in all uppercase for the Frobnitz-Interface
let result = map toUpperCase list
Improve this answer
2
  • 8
    grandpa always tells me to document the why instead of the what. So I would use the last version for imperative code as well.
    – Simon Bergot
    Nov 17, 2011 at 12:53
  • 3
    Your grandpa is right. I just wanted to demonstrate that certain comments that make sense nevertheless in the imperative realm are absolutely useless in the funtional.
    – Ingo
    Nov 17, 2011 at 14:06
11

The reason we document a function is that readers don't want or can't read the body of the function. For this reason, one should document large functions, even in functional languages. It does not matter if it's easy to understand what the function does by looking at its implementation.

Improve this answer
1
  • A good point. Especially if the reader is using some compiled library and can only see exposed function signatures and their comments. They'll never see the self-descriptive guts of your code.
    – FrustratedWithFormsDesigner
    Nov 17, 2011 at 15:14
3

Functions should be commented, if the function name and parameter names alone do not suffice to specify the contract.

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

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

In a nutshell, the contract defines what the function expects and what it guarantees. Strictly speaking, if GetEmployeeList returns a sorted list but does not say so in either the function name or the comment, a consumer of this function must not rely on this behavior. It's an undocumented implementation detail, and the author of GetEmployeeList has the freedom to change this behavior any time.

Improve this answer
2

The comment itself shouldn't contain an alternative description to what the code does (that actually is expressed by the code itself), but rather an explaination of the reasons why the code is written the way it is.

That said, I don't see any reason why a comment should per se be different in a functional language.

Improve this answer
1

I take the same approach to documenting all of my code:

  • Use descriptive names,
  • Add comments before any reasonably complicated logic if complicated logic can't be avoided,
  • Write an overview of the entire system,

If the name and type signature doesn't tell you exactly what the function does, you're usually doing it wrong.

Improve this answer
0

At age 25 you tend to remember things much better. As you get older and you are involved with multiple systems with legacy code (yes, the code you write today will be legacy code in 10-15 years) it can be very helpful if there are comments.

Improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.