Documenting Scala functional chains [closed]

Question

Scala (and functional programming, in general), advocates a style of programming where you produce functional "chains" of the form

collection.operation1(...).operation2(...)...

where the operations are various combinations of map, filter, etc.

Where the equivalent Java code might require 50 lines, the Scala code can be done in 1 or 2 lines. The functional chain can change an input collection to something completely different.

The disadvantage of the Scala code is that 10 minutes later (never mind 6 months later), I can't figure out what I was thinking, because the notation is so compact, and lacks type information (because of implied types).

How do you document this? Do you put a large block comment before the chain, changing an elegant 1 line solution into a bulky 40 line solution consisting of 39 lines of comment? Do you intersperse your comments like this?

collection.
  // Select the items that meet condition X
  filter(predicate_function).
  // Change these items from A's to B's
  map(transformation_function).
  // etc.

Something else? No documentation? (Leave them guessing. They'll never "downsize" you then, because no one else can maintain the code. :-))

Answer 1

If you find yourself writing comments at that detail level, you're just repeating what the code says.

For long functional chains, define new functions to replace parts of the chain. Give these meaningful names. Then you might be able to avoid comments. The names of these functions themselves should explain what they do.

The best comments are the ones that explain why the code does something. Well-written code should make the "how" obvious from the code itself.