Which docstring format should be followed? CONTRIBUTING.rst lists multiple formats.

[katecoded]

As said in the title, CONTRIBUTING.rst points to two different style guides for writing docstrings. In the Code Contribution Ideas section, it says beets follows PEP-257, while in the Style section, it says beets follows google's docstring format. Since these are two completely different formats, which should be followed?

I wanted to post this here before making an issue just in case the answer is somewhere obvious or I am missing something (I am looking to make a contribution to the docstrings of this project, for context). Thank you in advance!

[sampsyo]

Very good question; thanks for pointing out the inconsistency. Honestly, we haven't exactly converged on this, and the actual truth is that you're welcome to use whatever you think is right.

The somewhat more detailed answer is that the PEP-257 advice you pointed to is quite old (it comes from an older wiki page) and is what we've been using for a long time. A more recent spate of efforts to make beets more consistent ended up proposing we use a more complete style guide for docstrings. It wasn't exactly clear what the "right" one to settle on was, though; the Google guide was the least offensive and got the nod when @jtpavlock did such a bang-up job writing up the CONTRIBUTING.rst. So I think the status is that we would like to start moving toward Google style, but it's subject to revision as we get more experience with it.

I hope this helps! Sorry it's a little fuzzy.

[katecoded]

Okay, thank you - that makes sense and is very helpful! I will go with the Google style for now and see how everyone feels about it when I submit a PR. I am always happy to change it later.

[wisp3rwind]

Just to keep track of this: #4191 has some more discussion about this. Namely, @sampsyo commented

There is one piece that left me a little worried, though: personally, I have a somewhat averse reaction to Google's recommendation for verb tense. grimacing I'd be interested in others' opinions, but maybe we could consider sticking with Google's style except for this anti-PEP-257 aspect that I would find hard to adopt myself?

I notice that Google guide explicitly says to use descriptive verbs, which directly contradicts PEP 257's recommendation to use an imperative mood. Weird! That is going to be a very hard habit for me to break, personally… and it even makes me question whether we really do want to embrace the Google style wholeheartedly.

Why don't we go back to imperative verbs while we discuss a broader policy elsewhere?