Docstrings should be allowed to follow the license without a space

[charlie-rivos]

Docstrings are defined in PEP 257 as "A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition." When reuse adds a header, it forcibly adds a space before the docstring violating this principle.

When the style is set to Python and the first line in the file is a docstring, a space should not be added between the license and the docstring.

[floriansnow]

Thank you for opening this. The way I read PEP 257, an empty line is not an issue because an empty line is not a statement, neither is a comment. And as for legibility, the empty line is actually a good thing, so it should fit well with the Python philosophy.

[charlie-rivos]

Perhaps the spec is somewhat ambiguous. It could be interpreted that it is valid for there to be a space, but it is at least also valid that there is no space. The PR that I have linked here changes the behavior so that reuse will leave the space as-is, meaning that it won't forcibly insert a space and similarly won't remove the space if it exists.

This came up because reuse and https://github.com/PyCQA/docformatter disagree on if there should be a space here. I decided to open the PR here instead of on docformatter because my interpretation was that reuse should only focus on managing licenses and allow the user to format their code as they wish (such as using docformatter). Another formatting tool could decide that it wants a space here, and reuse should allow both of these.

[floriansnow]

Hm, I understand. However, this means that docformatter disagrees with other tools such as black and I think there needs to be agreement there first. At a quick glance, there are examples in the standard library that have the empty line, so what would docformatter do to those?

[charlie-rivos]

Docformatter always removes the space, so it would remove the space in the standard library. I can remove the wording of the patch to not say that reuse is not conformant to PEP 257 because that doesn't seem to be the case and it is simply a formatting preference.

Black does not disagree with Docformatter. Black does not format docstrings, so it will neither add nor remove a space after docstrings. This is the behavior I am requesting for reuse.

As you brought up, it seems valid to either have a space or not have a space. reuse is forcing there to always be a space. The patch I have sent will allow code that either has a space or does not have a space which will allow people to format their code as they wish. Is reuse expected to also be a formatting tool?

[charlie-rivos]

I have updated the issue and the respective PR to align to this new wording. I have removed references to PEP 257 because, as you have pointed out, this is not an issue with PEP 257. I have opted the wording to instead focus on providing users the choice of how they want to format their code, since both having the space and omitting the space conforms to PEP 257.

[charlie-rivos]

Why does reuse ever insert whitespace after the license? Is there a reason to insert the whitespace in any language? I would like this change for Python files so I can format my Python code differently, but I would imagine similar situations applying to other languages.

[charlie-rivos]

I realized I left references to PEP 257 in a comment in the MR so I changed the wording in the comment so that it is more in line with the wording in the commit description.

[charlie-rivos]

@floriansnow @carmenbianca any further comments on this or on the PR at #1136?