Create documentation explaining CSharpier formatting decisions

[belav]

Discussed in https://github.com/belav/csharpier/discussions/778

^{Originally posted by andrewrondeau-optirtc December 27, 2022}
Hi, apologies if this is a noob question!

Do you have any documentation that explicitly explains the style that CSharpier applies? (I like that it's opinionated, BTW.)

Even though I've run CSharpier on my codebase, I'd like to be able to read through a general description of the kinds of changes it makes to my code.

If I choose to integrate this into the workflow, it's a lot easier to explain it if I can point out specific style changes it will make, and changes it won't make.

[commonquail]

This is an area where google-java-format excels because of https://github.com/google/google-java-format/wiki/The-Rectangle-Rule and Prettier in comparison is an inconsistent mess. Faulty implementation notwithstanding, numerous presently open inconsistencies in and questions about CSharpier's behaviour would be neatly resolved in theory by adhering to the same principle as google-java-format.

I understand that CSharpier draws inspiration from Prettier. I am also saying in the same breath that Prettier needlessly faces several of these difficulties and does not represent the state of the art. For another perspective, rustfmt is somewhere in-between, condensing some things google-java-format would expand and expanding some things google-java-format would condense.

In chronological order, at least the following presently open issues raise questions about intended or desired behaviour; notably, many propose a solution that aligns with "the rectangle rule":

• Foreach formats weird #108
• Break before operator on expression bodied methods and variable declarations. #205
• ParenthesizedLambdaExpressions needs some work. #238
• Generic Property Breaking #243
• Improve formatting of Field with Array Initializer #290
• Constructor is breaking earlier than it should #292
• SwitchExpression - keep things on same line if possible #348
• BinaryExpression - Possibly change the way parens are formatted #356
• CoalesceExpression in InvocationExpression isn't very readable #449
• Improve formatting of Generics and InvocationExpressions #450
• Break InvocationExpression chain before breaking ArguementList #451
• Chained Assignment Improvement #452
• Generics with object creation needs some work #468
• Invocation with ObjectCreation is ugly #469
• Improve printing for lambda arguments #672
• Arithmetic, parentheses, and null coalescing #765
• Csharpier does strange indentation in long method chains #766
• Break long invocation chains if they have more than 4 (3?) invocations in them. #792
• Inconsistent line breaks with lambda notation #803
• Inconsistent breaking with lambdas with/without parens #836

[belav]

This is an area where google-java-format excels because of https://github.com/google/google-java-format/wiki/The-Rectangle-Rule

I think you may have linked to this in the past? I remember reading it after someone shared a link and am pretty sure I completely spaced on responding. I've been trying to keep it in mind while looking at any new changes I'm making, so thank you if that was you!

Prettier in comparison is an inconsistent mess.

I didn't really realize how inconsistent it could be at times until I started running into those issues with CSharpier. Following the way prettier formatted code did make it easier to build out CSharpier though, and I don't think anything major would need to change to start trying to follow the rectangle rule in most places.

I don't suppose you know of a playground for google-java-format? I found one for rustfmt right away, but haven't found the java one. If nothing else, after building the rider plugin for csharpier I am set up to code java locally.

[commonquail]

I think you may have linked to this in the past?

Yeah, that was me. I didn't really expect a reply. It's not like google-java-format doesn't have its own issues, including some caused by that principle, but it's the only tool I know of that has a fairly consistent style that is also explained by principle -- I've found that useful for comprehension but of course it helps that I also like the resulting style.

I'll add for the record, too, that none of this is meant as criticism and I still choose CSharpier. I just indexed the items that seemed to represent incidental (possibly unwanted) behaviour.

I don't suppose you know of a playground for google-java-format?

No, I've never come across a such. It's a self-contained jar file, however, so it's straightforward to run by hand, and there is https://plugins.jetbrains.com/plugin/8527-google-java-format.