We use Black for uncompromised code formatting. Every pull request is automatically checked as part of the linting process and we never merge submissions that diverge.
Summary of the most relevant points:
- Comments should be full sentences and end with a period.
- Imports should be ordered.
- Constants and the content of lists and dictionaries should be in alphabetical order.
It is advisable to adjust IDE or editor settings to match those requirements.
For some cases PEPs don't make a statement. This section covers our recommendations about the code style. Those points were collected from the existing code and based on what contributors and developers were using the most. This is basically a majority decision, thus you may not agree with it. But we would like to encourage you follow those recommendations to keep the code consistent.
The docstring in the file header should describe what the file is about.
There is no need to add the platform or component name to the log messages. This will be added automatically. Like
syslog messages there shouldn't be any period at the end. A widely used style is shown below but you are free to compose the messages as you like.
Do not print out API keys, tokens, usernames or passwords (even if they are wrong).
Also note that
_LOGGER.info is reserved for the core, use
_LOGGER.debug for anything else.
Ordering of imports
Instead of order the imports manually, use
Use new style string formatting
Prefer f-strings over
One exception is for logging which uses the percentage formatting. This is to avoid formatting the log message when it is suppressed.
Typing of functions
Either completely type a function or do not type a function at all.