* <<G6O.0730>> Code formatting
It's just astonishing how difficult a piece of code can be to read
when its author uses different conventions of style and formatting
than you're accustomed to. Beyond that, it's astonishing how
difficult it can be to read source code at all, particularly code
that is quite deeply nested and parenthetical.

I've removed the formatting from the following JS code, just to
examine how unlike human language things can get. This is a single
statement, a single 'line of code', if you will, and there's a lot
going on in it.

var args = require('tav').set( { url: { note: 'URL of the page to
parse' }, post:{ value:'', note:'Post parameters' } },'dom-node for
node.js',true);

How does that parse out into human language? Something like this:

Create a variable named args that refers to the object created by the
global function require('tav'). Run the set() function of that object
with the following arguments:
- An object with two properties, url and post. The value of url is an
object with a property named note, the value of which is the string
'URL of the page to parse'. The value of post is an object with two
properties: value, which contains an empty string, and note, which
contains the string 'Post parameters';
- The string 'dom-node for node.js';
- The value true.

The formatting the author used for that line is this:

var args = require('tav').set({
                                 url:{
                                       note:'URL of the page to
parse'
                                     },
                                 post:{
                                        value:'',
                                        note:'Post parameters'
                                      }
                               },'dom-node for node.js',true);

That, to my eyes, is hideous. Too much whitespace makes things almost
as hard to read as none. For me, it is much easier to read if
formatted differently, and we split it into a pair of statements
instead of one terse line:

args = require('tav');
args.set( { url: { note: 'URL of the page to parse' },
           post: { value:'', note:'Post parameters' } },
         'dom-node for node.js',
         true );

My general rule-of-thumb is that if a phrase/statement/clause can fit
on a single line, put it on a single line. If it can't, try to break
it into a series of statements/phrases/clauses that will. Don't put
onset brackets alone on a line. Coda brackets are okay.

--
Excerpted from:

PUBLIC NOTES (G)
http://alph.laemeur.com/txt/PUBNOTES-G
©2016 Adam C. Moore (LÆMEUR) <[email protected]>