On Sun, Nov 14, 2021 at 12:37 PM Ralf Gommers <ralf.gommers@gmail.com> wrote:

On Sun, Nov 14, 2021 at 6:14 PM Charles R Harris <charlesr.harris@gmail.com> wrote:
Hi All,

This post is for discussing the automatic code formatters for C/C++/*.py that are now available. The current options, as I see them, are clang-format (C/C++) and black (*.py, *.pyi, etc). Neither is perfect to my eye, but I think they are good enough at this point and would reduce amount of style nitpicking.


There is already a '.clang-format' file in the numpy repository. The main drawbacks that I see are:
  • no automatic spacing between function definitions,
  • all operators, including '*' and '/',  get spaces around them,
  • no extra indenting of continued 'if' conditions,
  • the order of includes is alphabetical within groups. The groups are currently defined in the 'clang-format' file, but there may still be problems with include order that we will need to fix.
I think those can be lived with. The results are good enough that I think it can replace the official C coding style for most things. The maximum line length is currently 79 characters.


The black formatter is much improved in its latest version and I think good enough to start using. The main drawbacks that I see are:
  • all operators, including '*' and '/',  get spaces around them,
  • very long strings are not broken into multiple lines,
  • lists, tuples, and function signatures are either on one line, or broken into multiple lines of one element/argument each,
  • the formatting of extended logical expressions could be improved to emphasize the priority of 'and' over 'or' operators
There is no current configuration in pyproject.toml, the default maximum line length is 88 characters. I note that setting the line length to 79 notably increases the number of line breaks needed. Note that double quotes are now preferred to single quotes.

I think that including black configuration in pyproject.toml would be a good idea, the main question is line length, 79 or 88 characters. The same question of line length can also be raised for clang-format. Lines much longer than 88 are characters are not only a problem for terminals, they are also hard to focus on if you have bad eyes, but lines longer
than 79 characters also reduce the number of line breaks needed.


I'd suggest:
(1) let's discuss `clang-format` for C/C++ separately from `black` for Python.
(2) to read https://github.com/scipy/scipy/pull/14330 and https://github.com/scipy/scipy/issues/14354 and then not even continue the discussion on `black`. A detailed proposal with an incremental formatter may have a chance here (xref `darker` and our `tools/linter.py`), a "let's just run black" one seems dead in the water given the people and opinions in the linked SciPy PR and issue from a few months ago.

I've found this wrapper around clang-format useful for making it behave more like black, in terms of running on a directory of files and producing nice diffs of changes:


It is a single MIT-licensed python file that could be vendored easily.