diff --git a/notes-go/lint-n-format.md b/notes-go/lint-n-format.md index d23d519..b247a89 100644 --- a/notes-go/lint-n-format.md +++ b/notes-go/lint-n-format.md @@ -38,6 +38,8 @@ One of the most famous go features is a built-in code formatter [gofmt](https:// ... +See [awesome-go-code-formatters](https://github.com/life4/awesome-go-code-formatters) for more tools. + ## Custom rules If you have a custom rule you'd like to validate or reformat in your project, there are few linters and tools that can be helpful: diff --git a/notes-python/black.md b/notes-python/black.md index 6fc51ed..45d8a88 100644 --- a/notes-python/black.md +++ b/notes-python/black.md @@ -109,7 +109,6 @@ exclude = ''' I never understand what the strange construction is it. Now I got it. It's regular expression! Why not a list of regexps? Ugh... - ## It's not extendable Another point of Black's philosophy is "there is only one style". So, it's against of plugins and any extendability: you cannot have any other rules except built-in in Black. And you can't disable them, of course. However, Black can't take care about everything. For example, using `.format` inside of log messages is a bad practice. Flake8 has plugin for it ([flake8-logging-format](https://github.com/globality-corp/flake8-logging-format)), but will we ever see this check in Black? I don't think so. @@ -118,13 +117,25 @@ Another point of Black's philosophy is "there is only one style". So, it's again Black only do changes. It can't give you feedback or make some changes that can affect your interfaces. For example, Flake8 has [flake8-mutable](https://github.com/ebeweber/flake8-mutable) plugin that prevents you from using mutable default arguments for function. Black can't do anything with it. -## It's one person decisions. +## It's one person decisions Ambv has done a great work. However, it's one-person project, as most of Open Source projects. Flake8 plugins made by different people and teams. You can think that these rules is incompatible, goes from different styleguides and you can't combine these plugins together. It's not true. I'm using almost all Flake8 plugins, and I have no experience when 2 plugins had different opinion about some code. -## Ok, what should I use? +## It's still in beta + +The Black documentation [explicitly states](https://github.com/psf/black#note-this-is-a-beta-product) that the project is still in beta test. From the practical perspective, that means that the code style changes in every release. So, if you want to use it in a project, be ready to take an actions: + +1. Lock the exact version of Black in your dependencies file. +1. When you upgrade to a newer version of black, be ready to reformat all the code. Keep in mind that it will complicate backports and cause a few git merge conflicts. +1. Make sure that everyone in the project uses exactly the same version of black. Explicitly ask everyone to upgrade black when its version in the project was changed. +1. If you enforce Black on CI, it's better to make the job optional (`allow_failure: true`). Otherwise, it will even more complicate backports and black version upgrade. + +## Alternatives + +Ok, let's talk about alternatives and when Black is a good choice. 1. Have a big ugly codebase that you want to make readable for yourself? Use [black](https://github.com/python/black). 1. Don't want to think about formatting for your little project? Use [black](https://github.com/python/black). 1. Have a big codebase that you can adopt for your codestyle? Use [yapf](https://github.com/google/yapf). +1. Do you want to improve your productivity working in an experienced team? Use [autopep8](https://github.com/hhatto/autopep8). 1. Want to have beautiful and consistent code in your team or big project? Enable [flake8](http://flake8.pycqa.org/en/latest/) on CI and add as much [flake8 plugins](https://github.com/DmytroLitvinov/awesome-flake8-extensions) as you can. Also, I recommend to have a look on [wemake-python-styleguide](https://github.com/wemake-services/wemake-python-styleguide) -- biggest collection of Flake8 rules. diff --git a/notes-python/lint-n-format.md b/notes-python/lint-n-format.md index 7e5f2fe..a5e8fe9 100644 --- a/notes-python/lint-n-format.md +++ b/notes-python/lint-n-format.md @@ -10,3 +10,22 @@ + [wemake-python-styleguide](https://github.com/wemake-services/wemake-python-styleguide) is a flake8/flakehell plugin, providing a lot of checks. It is fast, strict, and helpful, finds many bugs, style issues, enforces consistency. It is very opinionated, so you probably want to disable some (most of the) checks. See [awesome-flake8-extensions](https://github.com/DmytroLitvinov/awesome-flake8-extensions) for more plugins. + +## Formatters + +Python has quite a few code formatters with different code style and philosophy behind. + +There are 3 all-in-one code formatters, all of them are supported by VSCode out of the box: + ++ [autopep8](https://github.com/hhatto/autopep8) is the oldest and the least opinionated Python code formatter. It formats the code to follow [PEP-8](https://www.python.org/dev/peps/pep-0008/) and nothing else. Under the hood, it uses the mentioned above [pycodestyle](https://github.com/PyCQA/pycodestyle). So, if the project passes pycodestyle (or flake8) checks, you can safely use autopep8. ++ [black](https://github.com/python/black) is "uncompromising" and opinionated code formatter. The code style is close to PEP-8 (there are few exceptions) but also it has an opinion about pretty much everything. It has some issues that make it a bad choice for an experienced team. However, it can be a good choice for an unexperienced team, an open-source project, or for a quick formatting of an old and dirty code. See [Don't use Black in your team](https://articles.orsinium.dev/python/black/) for more information. ++ [yapf](https://github.com/google/yapf) is a code formatter from Google. Like black, it reformats everything. The main difference is that every small detail in yapf is configurable. It makes sense to use yapf for a project with a codestyle stat is different from PEP-8. However, if you have choice, prefer using PEP-8 for all projects. + +A few small but helpful formatters: + ++ [add-trailing-comma](https://github.com/asottile/add-trailing-comma) adds trailing commas to multiline function calls, function signatures, and literals. Also, it fixes indentation for closing braces. ++ [docformatter](https://github.com/myint/docformatter) formats docstrings according to [PEP-257](https://www.python.org/dev/peps/pep-0257/). ++ [pyupgrade](https://github.com/asottile/pyupgrade) changes the code to use newer Python features. It will replace old comprehensions style, old formatting via `%`, drop unicode and long literals, simplify `super` calls and much more. ++ [unify](https://github.com/myint/unify) formats string literals to use one style of quotes (single or double). + +See [awesome-python-code-formatters](https://github.com/life4/awesome-python-code-formatters) for more tools.