[GRASS-dev] Python and script header definitions for modules

[Vaclav Petras]

Black formatting is unrelated to the main issue here and, as Huidae
mentioned in #560, it is too late to discuss it. The place to do that was
#543 as stated in on grass-dev in February-April and June 1 threads and in
#766.

However, I think it is worth clarifying what went into the decision to use
Black.

https://github.com/OSGeo/grass-addons/pull/560#issuecomment-866803190
https://github.com/OSGeo/grass/issues/543
https://github.com/OSGeo/grass/pull/766#issuecomment-731637722
[February-April]
https://lists.osgeo.org/pipermail/grass-dev/2021-February/094993.html
[June 1] https://lists.osgeo.org/pipermail/grass-dev/2021-June/095199.html

On Sun, Jun 13, 2021 at 11:02 AM Huidae Cho <grass4u at gmail.com> wrote:

>
> It's a great discussion. I *personally* think that enforcing Black or
> Flake8 is less ideal [1], but coding consistency is always good, I agree.
> Just one excerpt from [1]: "Autoformatters like Black are soulless, they
> won't understand how each specific case will be most readable. This should
> always be the developer's concern." Anyway, I consider it a necessary evil.
>

I considered the blogpost when considering Black. It makes three "I would
only use Black if" points. Here are my thoughts.

"I would only use Black if: You have an old code base that has been made by
more than one generation of developers and you want to make it more or less
readable." Well, that's exactly our case. Our formatting was all over the
place even with many fixes we did in the past. I would add that if you need
to do it once as one of the blogspot comments mentions, you may as well
enforce it because you will end up in the same situation after a couple
years which I think was not acknowledged there. The other comments are
mentioning Darker which is enforcing Black, but only for the new code.
Combining that with the 'apply once to an old code base' approach, you get
our solution.

"I would only use Black if: You don't want to bother with the styling guide
on your little project." We don't want to bother with a styling guide and
way of enforcing it regardless of project size.

"I would only use Black if: You have a team of juniors that you don't
really want to keep track of but end up wanting a consistent code." We are
in a similar situation. We want clear rules and consistent results, just
instead of a team of juniors, we have all kinds of contributors.

It also mentions how Black aims at diffs which is exactly why Black is so
appealing since many people spend a lot of time reading diffs.

Finally, the statement from the blogpost, "...they won't understand how
each specific case will be most readable," seems to go directly against
"Special cases aren't special enough to break the rules." from PEP 20 --
The Zen of Python [2] or the more general one "your case is not special."

To address the line length issue as well, the number 88 we are using
(coming from Black) breaks PEP8 and this is unfortunate. However, I think
it falls under the next point from Zen of Python: "Although practicality
beats purity." for reasons discussed, e.g., in Black documentation [3].

[1] https://luminousmen.com/post/my-unpopular-opinion-about-black
-code-formatter
[2] https://www.python.org/dev/peps/pep-0020/
[3]
https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/grass-dev/attachments/20210627/ee6c3467/attachment-0001.html>