Code formatting, style guide enforcement and static checks

[RMeli]

I recently started using code formatting (with black), style guide enforcement (with flake8) and static code checks (with mypy). I tried to apply them to MDAnalysis for fun and came across to many warnings.

Describe the solution you'd like

I think it would be great to format MDA with black (or other tools) and then use flake8 and mypy (or other tools) to spot and fix possible problems.

Describe alternatives you've considered

There are other tools that can be considered: pylint, isort, ypaf, ...

Additional context

Many errors come from MDAnalysis/migration/.

You can have a look at this commit to see the result of automatic code formatting with black.

[richardjgowers]

We had (or have?) pylint on, but it sometimes throws annoying errors which stop a PR merging.

i think with something like black, we'd have to have every contributor follow the style, which would mean either a) instructions for everyone on how to apply it easily or b) some sort of CI system which fixes up the formatting on merging. Both seem like they'd add ongoing effort for not much real gain?

[RMeli]

@richardjgowers I just wanted to spark the discussion but I agree the ratio benefits/effort might be small. However, #2409 and #2411 could be easily spotted by static checks. I also have found some indentation errors here and there that will make the code fail when executed.

Automatic code formatting (with black or other) is useful only if used with pylint or flake8, so that it removes most of the useless formatting errors. (It might reduce commit diffs if everyone uses it, but this is a very marginal benefit). However, it's really easy to install (pip install black) and apply (black .).

[jbarnoud]

I am all in favour of linters and static analyzers. I am considering adding type hints when we would have dropped python 2. I am less keen on formating tools, though: the way I format my code is often deliberate and, sometimes, going against the convention helps with readability or other things.

[RMeli]

I think adding type hints will be a great!

I understand that automatic code formatting is not something every developer is willing to accept, but it would be the easiest way to remove most of the linting problems in one go at the beginning. I haven't tried pylint, but flake8 gives very reasonable complaints (when used after automatic code formatting).

Most of the tools can be configured in setup.cfg in order to reach a general consensus.

[tylerjereddy]

I'd suggest only applying the CI linting to the diff if we do this, rather than driving the full code base through a large amount of churn. SciPy is working on adopting something like this in: scipy/scipy#11423

I'd be cautious about adopting type hints---maybe if/when they become widely adopted at the base of our dependency tree in NumPy/SciPy, etc.

[RMeli]

I like the idea of linting only the diff! What is the drawback of type hints if they are not well adopted by the dependencies?

[tylerjereddy]

There may not be any major drawback, I just mean it could be sensible to wait to see what the rest of the ecosystem decides to do (if anything) about hinting in scientific code.

For example, NumPy has an experimental repo for type hinting with arrays: https://github.com/numpy/numpy-stubs

See also long-standing issue here: numpy/numpy#7370

Perhaps it may have some influence on what we might want to do.

[tylerjereddy]

Note that SciPy has started accepting PRs that add type hints to source code, so maybe the time for doing this is not really so far away. May want to wait until we officially drop Python 2 support, as noted above.

[lilyminium]

+1 on being apprehensive about autoformatters. My main objection is what they do to commit history. It's useful to look at a line of code and see who committed it in which PR, so you can check out any discussion and know who to direct questions to.

CI linting the diffs seem like a great idea and would remove some of the PEP8 comments on reviews.

[IAlibay]

Just tagging this additional discussion thread here.

[lilyminium]

https://github.com/marketplace/pep-8-speaks may be of interest.

Edit: instead of adding a check that can fail, it simply comments so contributors and reviewers can decide if they want to follow suggestions or not.