diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md index 8c3a30270d1..aa2dd881a9e 100644 --- a/docs/the_black_code_style/current_style.md +++ b/docs/the_black_code_style/current_style.md @@ -200,6 +200,16 @@ following field or method. This conforms to _Black_ won't insert empty lines after function docstrings unless that empty line is required due to an inner function starting immediately after. +### Comments + +_Black_ does not format comment contents, but it enforces two spaces between code and a +comment on the same line, and a space before the comment text begins. Some types of +comments that require specific spacing rules are respected: doc comments (`#: comment`), +section comments with long runs of hashes, and Spyder cells. Non-breaking spaces after +hashes are also preserved. Comments may sometimes be moved because of formatting +changes, which can break tools that assign special meaning to them. See +[AST before and after formatting](#ast-before-and-after-formatting) for more discussion. + ### Trailing commas _Black_ will add trailing commas to expressions that are split by comma where each diff --git a/tests/data/comments2.py b/tests/data/comments2.py index 221cb3fe143..4eea013151a 100644 --- a/tests/data/comments2.py +++ b/tests/data/comments2.py @@ -159,7 +159,7 @@ def _init_host(self, parsed) -> None: ####################### -instruction() +instruction()#comment with bad spacing # END COMMENTS # MORE END COMMENTS @@ -336,7 +336,7 @@ def _init_host(self, parsed) -> None: ####################### -instruction() +instruction() # comment with bad spacing # END COMMENTS # MORE END COMMENTS