(original) (raw)

On Tue, Dec 29, 2015 at 4:38 PM, Andrew Barnert <abarnert@yahoo.com> wrote:

\> Isn't the same thing true for every special method? There are lots of classes where \_\_add\_\_\_ just says "a.\_\_add\_\_(b) = a + b" or (better following the PEP) "Return self + value." But, in the rare case where the semantics of "a + b" are a little tricky (think of "a / b" for pathlib.Path), where else could you put it but \_\_add\_\_?
\>
\> Similarly, for most classes, there's only one of \_\_init\_\_ or \_\_new\_\_, and the construction/initialization semantics are simple enough to describe in one line of the class docstring--but when things are more complicated and need to be documented, where else would you put it?

Yeap. Note that I'm ok to include a docstring when the actual
behaviour would deviate from the expected one as per Reference Docs.
My point is to not make it mandatory.


\> I usually just don't bother. You can violate PEP 257 when it makes sense, just like PEP 8\. They're just guidelines, not iron-clad rules.

Yeap, but pep257 (the tool \[0\]) complains for \_\_init\_\_, and wanted to
know how serious was it.


\[0\] https://pypi.python.org/pypi/pep257