Wait, black requires all double quotes? What benefit does this provide? I have always only used single quotes (expect in the rare occasions where double quotes were necessary).

For that matter, why should we even use black? What does it provide that we don't get with flake8? If it is a different set of style rules, no thanks. If it is just some additional rules which are not included in flake8, then fine. But personally, I'm happy with flake8.

Black is a formatter that transforms code into a consistent representation, disregarding any formatting as initially written.

This is not a tradeoff I am interested in. If there is even a 1% chance that the output could look worse, then I'd rather custom craft the code myself.

I understand the irony of the fact that I dislike using a generator (of code or diagrams, etc) when I am developing and documenting another generator. The difference is that, except in rare circumstances, I don't look at the HTML generated by MkDocs, but I would be looking and, and likely later making edits to the code, etc.

Besides, its not hard to write code which meets flake8's requirements. With a good editor, most mistakes should never make it to a commit anyway.

black and isort (and autoflakes) are life-changers for me. I don't even have to think about the style when writing code: I just dump imports in whatever order at the top, and code with whatever spacing, line jumps or indentation (where indentation doesn't matter). Then I just run a "format" action and everything is perfectly formatted. It spares me time, mental energy, and movements (less typing on the keyboard for style adjustments).

you may note that the output of Black often looks worse than what was originally written

I disagree on the "often". It looks worse when you have function calls like

do_something(
    ax, ay, az,
    bx, by, bz,
)

...because the custom-crafted version groups args logically, while black will just put them on the same line or each one on a new line. But these cases (at least in the projects I write) are rare enough. And even if it does not look good, to be honest I don't care: the code is still perfectly readable.

Another advantage of using black is that you minimize the size of diffs in PRs. Though this can be enforced by flake8 rules I guess.

@pawamoy thanks for your comments. However, everything you said sounds worse to me than what we have now. Of course, we are all free to have our own opinions.

Everything, really 😅?

Of course! Just wanted to share on the subject 🙂

Everything, really 😅?

Yes, everything. Even this:

I don't even have to think about the style when writing code:

Thinking about the style helps me write better code. In over a decade of reviewing other people's code, the worst code has always been from people who clearly didn't think about style. Does that mean that every person who relies on black is a poor programmer? No, but why encourage that?

Meh, I disagree 😕

I guess the worst code you saw was from inexperienced programmers, so of course their style might have reflected their experience. Also, was it worst because of the style or because of the code semantics? How often did you see such bad code? Was there a formatter in place at that moment?

Asking myself if I should put the square bracket right after the parenthesis or on a new line doesn't help me at all writing better code. I'm really speaking about consistency here, consistency of spacing, quotes, line jumps and indentation. I can write very bad code with a perfect style without any formatter if I want to 😂

In the end I think the conclusion of "formatter = no active thinking = bad code encouragement" is false. Using a formatter helps you learn the rules, and also frees you from the actual formatting work. It doesn't prevent you from thinking about style. I actually still intuitively code with "style", but more and more am freeing myself from this burden. I don't think it makes me write less good code.

MkDocs itself has style inconsistencies. As a contributor, seeing that I can write a docstring like this or like that could let me think "they don't care about the style, so I'll write my docstring like this". A formatter would fix that!

EDIT: I'm not trying to make you change your decision, I'm just curious about how our experiences are different or similar 🙂 I have way less years of code/review experience than you 😅

I was reluctant to respond to this PR since it got closed quickly but I guess that it could provide some insights for people that might come across it later and I felt bad in letting @pawamoy alone on something I proposed.

First of all, this PR was not intended to create a personal opinion/experience war but instead try to shed the light on a perspective that this project had maybe not considered yet about its code readability and consistency regarding both its maintainers and contributors. Since 1.2 is around the corner, I felt it could be a nice time to make this move.

A good and concise rationale to a formatting tool vs a code linter was given by Matt Layman here.

I like the analogy with the go language creators as they embedded go fmt in the language from the start. This choice was made from experience that showed that this tooling approach has value on both projects and people (even if not for oneself, surely for others). There's no debate on this in go and it benefits the community and their projects without doubt.

I think that the fact that the Python Software Foundation ended up endorsing and hosting black also tells us that it's always interesting to change our point of view on such a controversial topic.

So once again, personal beliefs and habits have no play in my opinion on such a topic. As a matter a fact I used to use simple quotes like @waylan and a lot of my coding style was shaken hard by black and required me to adjust and abandon most of my habits. I know and understand the personal feeling that tools like this generate.

But the point of such a tool is to follow a purpose that is beyond ourselves: it's made for projects and all the people who contribute to it. Repeat it enough and you get overall improvement through convergence. Ask yourself: what would have been the benefits for the whole Python community if the language had included a python fmt tool from the start?

If this questioning has no resonance to the maintainers of MkDocs for their project so be it: their project, their rules and I will always gladly stand by them. I just humbly tried to make some points with no ego attached to them and I don't want to make a big deal out of it.

I have way less years of code/review experience than you sweat_smile

Don't worry about that @pawamoy ; I experienced first hand the impacts of enforcing code formatting tools on hundreds of Python projects and developers in my company and obviously feel differently from Waylan ;)