Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Diff friendly literals #80

Closed
johan opened this Issue Nov 29, 2011 · 6 comments

Comments

Projects
None yet
5 participants

johan commented Nov 29, 2011

I'd like a "diff friendly literals" indentation style that puts element separator commas and leading { or [ characters at the beginning of the line instead of at the end of it, and ] and } characters on a line of their own.

I first encountered this indentation style for literals (and function calls with lots of arguments spread across multiple lines):

{ "online": true
, "null": null
, "japanese": "明日がある。"
, "empty": ""
, "number": 243
, "object":
  { "It may look a bit weird, at first": "but it's great for development,"
  , "array":
    [ 1
    , 2
    , [ 1
      , 2
      , { "as adding or removing values": "just changes the lines involved,"
        }
      ]
    , "and never any surrounding lines with just a comma added or removed."
    , "This makes diffs look way prettier and cleaner in github changesets."
    ]
  , "more\u0000challenging": "stuff \t with \b misc \f control ☠ codes\r\n"
  }
}

It looked weird and broken enough for me to ponder why I reacted strongly to it and why anyone would possibly prefer it, and it immediately dawned on me: because it solves an even more annoying problem:

In line-based version control systems (read: all of them), whenever you add or remove a property in a chunk of JSON, the diff touches not just the lines of the new properties you added, but also changes the line before it which now gets another comma character in place of the ] or } that was there before, which leads to uglier changesets.

The above indentation style doesn't have that problem (except in the rare case when an empty object or array becomes not so, and vice versa), as each new item comes with its own comma, on its own line.

johan commented Nov 29, 2011

I patched up the Firefox JSONView extension a while ago to employ this layout (xpi at http://ecmanaut.blogspot.com/2010/09/jsonview-with-copy-paste-support.html for the curious), as it's also very copy-paste friendly (you can easily double click to select lines, and see that you copy everything on the same "comma indentation level" in effect), and that's where I grabbed the above example literal (I just filtered out the spammier parts; sorry about that).

I love this style. +1.

Contributor

einars commented Nov 29, 2011

That's intense bending backwards to endure the imperfections of the tools
, I can't support that
.

That said
, I admit using variations of this syntax myself
, though not for the diff reasons
, but for the sake of simplified ordering maintenance
— most notably for printf's
:

printf("%s%s%s"
  , foo
  , bar
  , baz
);
// ^^^^ can be reordered without struggling with commas

johan commented Nov 29, 2011

I'm not saying it's the one thing it's got going for it, but it's the first one I came up with, trying to find its raison d'être.

Like anything with syntactic code style it's a matter of taste and preference, and I now find this way easier both to read, write and work with in general, having used it a couple of months at most. I think it's various aspects of your third point that add the most.

I never tried applying it to English, but your example surprisingly gained clarity from it, despite probably intending to mark its ridiculous looks. :-) As suggested in my post above, I had a caustic reaction to this thing too initially, but decided to prove myself right or wrong about it empirically by using it for a bit, and I am not looking back about it.

Might be of interest: One sentence per line, please

Contributor

bitwiseman commented Jan 30, 2015

Please take a look at branch feature/comma-first - e5bfcf3

Tell me if this is a sufficient first step towards what you want that I should add it to the next release.

@bitwiseman bitwiseman closed this in f8cf725 Mar 5, 2015

@Kingwl Kingwl pushed a commit to Kingwl/js-beautify that referenced this issue Sep 18, 2017

steinsphang fix issue #73 and #80 912ec18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment