* <<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) <adam@laemeur.com>