title: Documenting Scala functional chains
body: <p>Scala (and functional programming, in general), advocates a style of programming where you produce functional "chains" of the form</p>
  
  <p><em>collection.operation1(...).operation2(...)...</em></p>
  
  <p>where the operations are various combinations of <code>map</code>, <code>filter</code>, etc.</p>
  
  <p>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.</p>
  
  <p>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).</p>
  
  <p>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?</p>
  
  <pre><code>collection.
    // Select the items that meet condition X
    filter(predicate_function).
    // Change these items from A's to B's
    map(transformation_function).
    // etc.
  </code></pre>
  
  <p>Something else? No documentation? (Leave them guessing. They'll never "downsize" you then, because no one else can maintain the code. :-))</p>