Further specify guideline for continuation lines

[NathanLovato]

What constitutes a continuation line exactly? The official style guide does not specify it very granularly. It only has this rule:

Use 2 indent levels to distinguish continuation lines from regular code blocks.

effect.interpolate_property(sprite, "transform/scale",
		sprite.get_scale(), Vector2(2.0, 2.0), 0.3,
		Tween.TRANS_QUAD, Tween.EASE_OUT)

Does it apply if we lay all the arguments vertically? When defining enums, dictionaries, etc. we use a single indentation by default. For now, the formatter considers most line wraps to be continuations. But perhaps the only case where this should truly apply is the case written above or when a line ends with a backslash.

If someone has experience developing/contributing to formatters or has ideas about this, feedback's most welcome.

The formatter would ideally never format like the above to me, but rather more like this:

effect.interpolate_property(
	sprite, "transform/scale", sprite.get_scale(), Vector2(2.0, 2.0),
	0.3, Tween.TRANS_QUAD, Tween.EASE_OUT
)

Or a variant of this, all I mean with this example is that I would always have the arguments separated from the function identifier, on separate lines.

Side notes on hinting line packing from the user

One feature that was interesting with the library we previouysly used for this formatter is it allowed you to hint whether to keep something on one line or wrap it over multiple lines. By inserting line returns.

When it comes to packing and wrapping lines, we could do something automatic by default, and also have a system like Zig's formatter, where you can yourself insert a line return to indicate how many arguments you want per line. For example, something like this could tell the formatter "I want two arguments per line"

effect.interpolate_property(
	sprite, "transform/scale",
	sprite.get_scale(), Vector2(2.0, 2.0),	0.3, Tween.TRANS_QUAD, Tween.EASE_OUT)

And format into this:

effect.interpolate_property(
	sprite, "transform/scale",
	sprite.get_scale(), Vector2(2.0, 2.0),
	0.3, Tween.TRANS_QUAD,
	Tween.EASE_OUT
)

This is just one example, the idea is this gives you optional control on top of a "just works" default behavior. It's particularly useful for some data structures like an array representing a grid or matrix:

var grid_3_by_3 = [0, 0, 1, 0, 0, 0, 1, 1, 0]

You could insert a line return like this, after 3 items:

var grid_3_by_3 = [0, 0, 1,
0, 0, 0, 1, 1, 0]

And get this:

var grid_3_by_3 = [
	0, 0, 1,
	0, 0, 0,
	1, 1, 0
]

Right now I've implemented an automatic rule for a few cases where, when a line is too long, the system tries to balance out the lines with an equal number of expression parts or elements per line.

To be defined. I'm just dumping some notes as my teammate pointed out this possibility

[skison]

I would say that the double indents tend to feel excessive & unnecessary in cases where there is already a closing line that helps to disambiguate the scope, like in your examples where a closing bracket ), ], or } is used on its own line.

Where I have found the convention handy is in the rarer cases where I intentionally don't have a closing bracket on its own line, like when I have a method with a params list that spans 2 lines, and I'd rather not split them out vertically, e.g.

func my_function(param_1: int, param_2: int,
        param_3: int, param_4: int) -> void:
    ...

I will occasionally stick to this scheme to help save screen space when it seems like splitting all the params out onto separate lines wouldn't buy any significant clarity or benefit over keeping them inline. Sometimes it's just nicer to see more of the code on screen at once! But this is a pretty subjective thing to judge, and I wouldn't necessarily expect a formatter to make that judgement automatically. If it can be signalled to the formatter somehow which way it should format, either by the existence of a backslash, the lack of a closing bracket on a newline, or something else that can be done inline, that would be great!

[NathanLovato]

Thank you very much for taking some time to think about this! If you have examples from your code where you particularly enjoy one form of packing or you find it more readable than another, that'd be most welcome, be it just to start compiling a little library of the patterns people like the most.

The mindset with which I approach this tool is looking to make it as transparent as possible and working as well as possible for the majority of people out of the box. So the majority needs no configuration, nothing, just running it. And then on top of that, I'm looking to add (ideally, a small) set of tools and options that give users control over things that are really important for them.

[NathanLovato]

From what I understand of the official style guide, everything like function calls with enough arguments, chains of expressions, etc. that wrap over multiple lines are continuation lines, except for data structures like arrays and dictionaries, or enum definitions. So the default, to stay true to the official style guide, would be double indents for all that if my understanding's correct.