What about comments before functions?

[funkyfuture]

i don't know whether black handles this phenomenon purposely this way. i usually put annotations regarding a specific function in general right before it's definition:

# foobar functions


def bar() -> None:
    pass

# TODO add type annotations
def foo():
    pass

black adds two lines between the annotation and a specific function which looks like general, rather module oriented comments or 'section headings' i usually use as well:

# foobar functions


def bar() -> None:
    pass


# TODO add type annotations


def foo():
    pass

are there rationales i'm not aware of that lead to this transformation or could this behaviour get changed?

edit: interestingly the snippets in the README also contain such style.

[ambv]

Black used to format comments before functions like you're saying (hence the outdated README). This is problematic to implement:

• in this case we will destroy section headings which are way more common;
• or we have to somehow detect which is which, this is tricky to do correctly and will always result with decisions that look wrong to a human.

So, I cut the Gordian knot and said: if you want to comment on a function, do it in the docstring or as a first comment inside the function body. This is in the README:

Note: if you provide me with a pull request that does differentiate between section headings and regular standalone comments that precede a function, I will happily accept it. I just decided this would be a time sink for me and I have higher priorities (see "Getting to beta") now.

[funkyfuture]

okay, so keeping comments that are separated from a function defintion with only one newline sticky to that defintion would be acceptable and not break other paradigms?

[funkyfuture]

just as a note: comments preceeding variable assignments are untouched.

[ambv]

keeping comments that are separated from a function defintion with only one newline sticky to that defintion would be acceptable

Yes.

comments preceeding variable assignments are untouched

Yes, separation comes from enforcing the "one empty line" or "two empty lines" before a function/class definition in PEP 8. For other statements, there's no such rule so it's easier to keep them sticky.

[cricalix]

I take it this 'before function' behaviour is also what affects 'before a class definition'? I'm using a few comments in a file that contains a bunch of classes to note that 'all of these are related to X', and the same double-spacing is occurring.