-
Notifications
You must be signed in to change notification settings - Fork 2.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Blank line after docstring... or not. #2370
Comments
Isn't this a case of (referring the docs):
So working as intended and documented.
Reasonable proposal, I like this! |
Well, indeed the doc describes this behavior, but I think this should be treated separately. e.g. this code looks inconsistent and should be reformatted: def foo():
"""docstring"""
return 0
def bar():
"""docstring"""
return 0
def baz():
"""docstring"""
return 0 |
I agree and would also like to see Black have an opinion in the case where there is no docstring, my personal preference is no line between function def and first line of the body, but having it take a position one way or the other matters more to me than which position. echoing @PabloLec this code looks inconsistent and should be reformatted. def foo():
return 0
def bar():
return 0
def baz():
return 0 |
Also: #1872 |
Also related, perhaps not worth a separate issue (please mention if it should be): the placement of the last triple quotes for last line of the docstring itself. Sample; all of these are left as-is, but most of these should in my opinion get a treatment. This is probably my number one issue with black. Please stick with being opinionated :)
On one hand doing the same as for single-line docstrings, triple quotes on same line and no newline after, it is consistent. On the other hand the example for https://www.python.org/dev/peps/pep-0257 shows the triple quotes on the next line and no blank line after, which seems to be used most in the standard library (only had a quick look though). Since this is about opinions, let's express one: I'd be in favor of consistency so no blank line after (at least for functions, for classes and modules should remain as-is) and triple quotes attached to the text (after all that's how the docstring starts as well). |
I'm not 100 % sure if we should do it. I'd say I'm moderately in favor of it 😄 But if we do, my preference would be no blank lines: def f():
pass
def f():
"""Doc."""
return stuff
def f():
"""
Multiline doc.
With some explanation.
"""
return stuff That might be influenced a lot by the fact that an IDE will highlight the docstring very differently from the following code, which is a good visual aid. But most people should be using one anyway. |
Now that you mention it; I didn't consider the start of doc strings, but that's another case that should imo be treated and the newline erradicated; I'd like
or perhaps the seemingly more common
but not both, and also none of the other shenanigans like extra newlines before the opening |
Well that's a can of worms too 😅 but I definitely prefer either on one line, or all at the same level, like I wrote above. |
I looked around a bit and this at the end of
seems to fix first/last lines of docstrings, combined with
at the end of |
Just a quick bump, I tried reaching out and offer help on main communication means a few times within the past months but no response so, yeah. |
Module docstrings are already being handled by #2996. It's not a big stretch to start applying that elsewhere as well. We'll just have to agree to do it. And us (potentially) removing the lines in module docstrings would be in line with my preference above. |
I vote for no blank line after the docstring. I discovered this issue, because I was rewriting a file so that it complied with |
I know some tools will enforce PEP 257, but for non-tiny functions, it just looks weird to have no blank line, e.g.: @torch.no_grad()
def inference(
model: CompressionModel,
x: torch.Tensor,
skip_compress: bool = False,
skip_decompress: bool = False,
criterion: Optional[TCriterion] = None,
min_div: int = 64,
*,
lmbda_idx: int = None,
lmbda: float = None,
) -> dict[str, Any]:
"""Run compression model on image batch."""
if lmbda_idx is not None:
assert lmbda is None
lmbda = model.lambdas[lmbda_idx]
... versus: @torch.no_grad()
def inference(
model: CompressionModel,
x: torch.Tensor,
skip_compress: bool = False,
skip_decompress: bool = False,
criterion: Optional[TCriterion] = None,
min_div: int = 64,
*,
lmbda_idx: int = None,
lmbda: float = None,
) -> dict[str, Any]:
"""Run compression model on image batch."""
if lmbda_idx is not None:
assert lmbda is None
lmbda = model.lambdas[lmbda_idx]
... |
As mentioned in #4043, I lean towards not doing anything here. I feel that if we do something here, it should not be to always strip blank lines. Doing so would run in to the same readability issues that has made previous blank line changes controversial (see the comment above, #4043, etc). It would be inconsistent with how Black treats module and class docstrings. The examples in this issue arguing for stripping the blank line are all toy code. |
Since Black has the goal of not allowing too much customization to avoid too many variations out in the nature,
"""
My function:
- part 1: blabla
- part 2: blabla
- part 3: blabla
""" And inside function body: # Part 1 : Blabla
# Blabla
# Blabla
bla = blabla(x,y,z)
...
# Part 2 : Blabla
# Blabla
# Blabla
bla = blabla(x,y,z)
... etc. Moreover in linked issue #902, someone argued about the case of a comment just after the docstring: """
My function:
- part 1: blabla
- part 2: blabla
- part 3: blabla
"""
# Part 1 : Blabla
# Blabla
# Blabla
bla = blabla(x,y,z) is slightly ugly. """
My function:
- part 1: blabla
- part 2: blabla
- part 3: blabla
"""
#
# Part 1 : Blabla
# Blabla
# Blabla
bla = blabla(x,y,z) is also slightly ugly and maybe more readable, """
My function:
- part 1: blabla
- part 2: blabla
- part 3: blabla
"""
# ----------------------
# Part 1 : Blabla
# Blabla
# Blabla
# ----------------------
bla = blabla(x,y,z) is ok. |
I agree with @hauntsaninja above; we'll leave this unchanged. |
Describe the style change
Currently, black does not check blank lines between functions docstring and body.
That means both these options are valid:
As black is
uncompromising
andopinionated
, I guess this should be taken into account.Personally I tend to put a blank line but looking at the only potential reference PEP 257, there is no blank lines in given examples.
Whether we enforce the blank line or not, black should take care of this as this results in easy style inconsistency.
I'd say we should follow PEP 257 no blank line example.
Comment your opinion so that this issue can be refered to in a PR fixing this.
If there is no consensus, we could organize a jousting match to settle this.
The text was updated successfully, but these errors were encountered: