Update code formatting advice (#302)

* Update code formatting advice

* Tweak string formatting.

docs/development_guidelines.md

@@ -2,37 +2,21 @@
 title: "Style guidelines"
 ---
 
-Home Assistant enforces strict [PEP8 style](https://www.python.org/dev/peps/pep-0008/) and [PEP 257 (Docstring Conventions)](https://www.python.org/dev/peps/pep-0257/) compliance on all code submitted. We automatically test every pull request as part of the linting process.
+Home Assistant enforces quite strict [PEP8 style](https://www.python.org/dev/peps/pep-0008/) and [PEP 257 (Docstring Conventions)](https://www.python.org/dev/peps/pep-0257/) compliance on all code submitted.
+
+We use [Black](https://github.com/psf/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:
 
-- Line length is limited to 79 characters (see below).
-- Use 4 spaces per indentation level. We don't use tabs.
 - Comments should be full sentences and end with a period.
 - [Imports](https://www.python.org/dev/peps/pep-0008/#imports) should be ordered.
 - Constants and the content of lists and dictionaries should be in alphabetical order.
-- Avoid trailing whitespace but surround binary operators with a single space.
-- Line separator should be set to `LF`.
 
-The maximum line length comes directly from the [PEP8 style guide](https://www.python.org/dev/peps/pep-0008/#maximum-line-length), and is also used by the Python standard library. All code must pass these linting checks, and no exceptions will be made. There have already been numerous requests to increase the maximum line length, but after evaluating the options, the Home Assistant maintainers have decided to stay at 79 characters. This decision is final.
+It is advisable to adjust IDE or editor settings to match those requirements.
-
-Those points may require that you adjust your IDE or editor settings.
 
 ## Our recommendations
 
-For some cases [PEPs](https://www.python.org/dev/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 unified.
+For some cases [PEPs](https://www.python.org/dev/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.
-
-### Quotes
-
-Use single quotes `'` for single word and `"` for multiple words or sentences.
-
-```python
-ATTR_WATERLEVEL = 'level'
-CONF_ATTRIBUTION = "Data provided by the WUnderground weather service"
-SENSOR_TYPES = {
-    'alerts': ['Alerts', None],
-}
-```
 
 ### File headers
 
@@ -44,7 +28,7 @@ The docstring in the file header should describe what the file is about.
 
 ### Log messages
 
-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. Try to avoid brackets and additional quotes around the output to make it easier for users to parse the log. A widely style is shown below but you are free to compose the messages as you like.
+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.
 
 ```python
 _LOGGER.error("No route to device: %s", self._resource)
@@ -54,8 +38,8 @@ _LOGGER.error("No route to device: %s", self._resource)
 2017-05-01 14:28:07 ERROR [homeassistant.components.sensor.arest] No route to device: 192.168.0.18
 ```
 
-Don't print out wrong API keys, tokens, usernames, or passwords.
+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` in anything else.
+Also note that `_LOGGER.info` is reserved for the core, use `_LOGGER.debug` for anything else.
 
 ### Ordering of imports
 
@@ -68,14 +52,17 @@ $ isort homeassistant/components/sensor/fixer.py
 
 ### Use new style string formatting
 
-Prefer [new style string formatting](https://www.python.org/dev/peps/pep-3101/) over old.
+Prefer [f-strings](https://docs.python.org/3/reference/lexical_analysis.html#f-strings) over `%` or `str.format`.
 
 ```python
+# New
+f"{some_value} {some_other_value}"
+# Old, wrong
 "{} {}".format('New', 'style')
 "%s %s" % ('Old', 'style')
 ```
 
-Except when doing logging here the format is:
+One exception is for logging which uses the percentage formatting. This is to avoid formatting the log message when it is suppressed.
 
 ```python
 _LOGGER.info("Can't connect to the webservice %s at %s", string1, string2)