Automated code formatting

[Flashing-Blinkenlights]

As people using different development environments contribute to this repository, it might be prudent to adopt an automated code formatter, or alternatively specify a code formatting guide, to allow for code to be compared without getting bogged down in changed whitespace.
Additional formatters such as isort may also be adopted.

The most widely adopted Python code formatter is Black, which is an opinionated formatter with limited configurability.
If a custom configuration is used, it may be sensible to include it in the repository and/or require it as a hook and/or automatically apply it using GitHub actions to improve adoption rates and lower the barrier of use.

[avdstaaij]

Adding an automated formatter or a formatting guide is certainly a good idea! It would save time for both contributors and the maintainer (me) by avoiding needless discussion in PRs.

An automated formatter would be the most convenient. I personally kind of dislike automated formatters since custom formatting can sometimes greatly enhance readability, but the benefits are undeniable.

The automated formatter black (playground) indeed seems like a logical choice, given its popularity.
Like you said, it has very little configurability: only the line length and some tiny details can be adjusted. This is by design: it's supposed to prevent users from arguing with each other over settings.

Now, I do have to say that I am strongly opposed to black's policy of non-configurability, though I do get where they're coming from (and they're honest about it). I find it unfortunate that such an opinionated formatter gained so much traction in the Python ecosystem. However, it so happens that black's style almost entirely coincides with my preferences, so this is in practice not a big issue. There are a few minor things that I dislike, such as it not collapsing nested parentheses/brackets and its sometimes strange line break locations, but I can live with them.

There's another popular autoformatter, yapf, which does have configurability. If it works as well as black and can also be integrated as well as it, I would prefer that one.

The one thing I really dislike about both of these formatters is that they remove alignment whitespace, though pretty much ever autoformatter does that. I'm aware that many people disagree with me, but I find that alignment can often make code much more readable. It takes a bit more effort to write and may cause larger diffs, but code is read much more often than it's written.

Some comparisons:

Constant dictionary

With alignment:

DYE_COLORS = {
    "white":      "0xF9FFFE",
    "orange":     "0xF9801D",
    "magenta":    "0xC74EBD",
    "light_blue": "0x3AB3DA",
    "yellow":     "0xFED83D",
    "lime":       "0x80C71F",
    "pink":       "0xF38BAA",
    "gray":       "0x474F52",
    "light_gray": "0x9D9D97",
    "cyan":       "0x169C9C",
    "purple":     "0x8932B8",
    "blue":       "0x3C44AA",
    "brown":      "0x835432",
    "green":      "0x5E7C16",
    "red":        "0xB02E26",
    "black":      "0x1D1D21",
}

Without alignment:

DYE_COLORS = {
    "white": "0xF9FFFE",
    "orange": "0xF9801D",
    "magenta": "0xC74EBD",
    "light_blue": "0x3AB3DA",
    "yellow": "0xFED83D",
    "lime": "0x80C71F",
    "pink": "0xF38BAA",
    "gray": "0x474F52",
    "light_gray": "0x9D9D97",
    "cyan": "0x169C9C",
    "purple": "0x8932B8",
    "blue": "0x3C44AA",
    "brown": "0x835432",
    "green": "0x5E7C16",
    "red": "0xB02E26",
    "black": "0x1D1D21",
}

Bespoke case

With alignment:

octants: List[ivec3] = [
    ivec3(x0 + e.x + dx, y0 + e.y + dy, z0 + e.z + dz),
    ivec3(x0       - dx, y0 + e.y + dy, z0 + e.z + dz),
    ivec3(x0 + e.x + dx, y0       - dy, z0 + e.z + dz),
    ivec3(x0       - dx, y0       - dy, z0 + e.z + dz),
    ivec3(x0 + e.x + dx, y0 + e.y + dy, z0       - dz),
    ivec3(x0       - dx, y0 + e.y + dy, z0       - dz),
    ivec3(x0 + e.x + dx, y0       - dy, z0       - dz),
    ivec3(x0       - dx, y0       - dy, z0       - dz),
]

Without alignment:

octants: List[ivec3] = [
    ivec3(x0 + e.x + dx, y0 + e.y + dy, z0 + e.z + dz),
    ivec3(x0 - dx, y0 + e.y + dy, z0 + e.z + dz),
    ivec3(x0 + e.x + dx, y0 - dy, z0 + e.z + dz),
    ivec3(x0 - dx, y0 - dy, z0 + e.z + dz),
    ivec3(x0 + e.x + dx, y0 + e.y + dy, z0 - dz),
    ivec3(x0 - dx, y0 + e.y + dy, z0 - dz),
    ivec3(x0 + e.x + dx, y0 - dy, z0 - dz),
    ivec3(x0 - dx, y0 - dy, z0 - dz),
]

However, it seems that for both of these autoformatters, it's actually possible to locally disable formatting for a range of lines or a single value with a special comment, which pretty much solves this problem! So, to conclude, I do think one of these autoformatters is the way to go.

If we adopt an autoformatter, we probably want to set it up with git hooks so that pushed code is automatically formatted. That would lower the barrier to entry the most.

As a final note, formatting the library should wait until after the documentation has been merged (see the docs-sphinx branch), since there would be tons of annoying conflicts otherwise. But if someone wants to set up the git hooks in a PR already, that would be helpful!

tl;dr

Summary of this ramble: yes, we should adopt an autoformatter. Preferably yapf if it works well, otherwise black. For both formatters, we can use special comments to locally disable formatting in places were alignment is used for readability. We should set up git hooks so that pushed code is automatically formatted. However, formatting the code should wait until the documentation (docs-sphinx branch) has been merged.