Facundo Batista writes:

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 disagree with the exception you're making for ‘__init__’. The parameters to that function (and how the function behaves in response) should be documented in the docstring, just as for any other function.

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

Omitting a docstring violates PEP 257, regardless which function we're talking about. So the tool is correct to complain. -- \ “If we don't believe in freedom of expression for people we | `\ despise, we don't believe in it at all.” —Noam Chomsky, | _o__) 1992-11-25 | Ben Finney

On Tue, Dec 29, 2015 at 1:03 PM, Facundo Batista wrote:

On Tue, Dec 29, 2015 at 4:38 PM, Andrew Barnert 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

That is the tool's fault. I personally hate with a vengeance that there are tools named after style guide PEPs that claim to enforce the guidelines from those PEPs. The tools' rigidity and simplicity reflects badly on the PEPs, which try hard not to be rigid or simplistic. -- --Guido van Rossum (python.org/~guido)

On 4 January 2016 at 17:01, Terry Reedy wrote:

Ask the PSF/pypi people to either prohibit such names or require a disclaimer of some sort. They are inherently confusing: "I took a look at pep008" does not mean that one even looked at the PEP. Even when the context makes clear that the referent is the module, there is confusion as to its authoritativeness. That Facudo would post here about the module's output illustrates that. To me, the name copying violates our informal trademark within Pythonland on 'PEP####'.

I don't think that's the right answer, as opinionated tools do serve a useful purpose in preventing bikeshedding during code review (people *expect* computers to be annoyingly pedantic, which frees up the human reviewers to focus on higher level concerns). As projects evolve over time, they may develop their own tweaks and customisations in their style guide and switch to a more configurable tool, or they may not. When some of the default settings for the pep8 utility became a problem, I was able to talk to the developers and persuade them to tune their defaults to be more in line with the actual PEP text, and keep their extensions to optional settings. A similar approach may work for PEP 257, by clarifying which aspects tools should be leaving to human judgement (beyond the question of whether or not to opt in to following PEP 257 at all - it's far less universal than PEP 8). Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

On Sun, Jan 3, 2016 at 11:49 PM, Nick Coghlan wrote:

On 4 January 2016 at 17:01, Terry Reedy wrote:

...

Ask the PSF/pypi people to either prohibit such names or require a disclaimer of some sort. They are inherently confusing: "I took a look at pep008" does not mean that one even looked at the PEP. Even when the context makes clear that the referent is the module, there is confusion as to its authoritativeness. That Facudo would post here about the module's output illustrates that. To me, the name copying violates our informal trademark within Pythonland on 'PEP####'.

I don't think that's the right answer, as opinionated tools do serve a useful purpose in preventing bikeshedding during code review (people *expect* computers to be annoyingly pedantic, which frees up the human reviewers to focus on higher level concerns). As projects evolve over time, they may develop their own tweaks and customisations in their style guide and switch to a more configurable tool, or they may not.

When some of the default settings for the pep8 utility became a problem, I was able to talk to the developers and persuade them to tune their defaults to be more in line with the actual PEP text, and keep their extensions to optional settings.

A similar approach may work for PEP 257, by clarifying which aspects tools should be leaving to human judgement (beyond the question of whether or not to opt in to following PEP 257 at all - it's far less universal than PEP 8).

Hm. I don't want the PSF to flex its muscles about trademarks, but I still don't like that there are tools named after PEPs (especially since the tools are not written by the same people that wrote the PEPs). I still recall the first time someone emailed me about a "pep8" issue (I had never heard of the tool by that name) and I was thoroughly confused for a long time. That said I expect it's too late to try and get the pep8 authors to rename it; but I filed an issue with the pep257 project and they are going to change the name: https://github.com/GreenSteam/pep257/issues/172 . FWIW I am happy that the tools exist! They can be very useful and I use pep8 myself. But I always let it know who's boss. :-) -- --Guido van Rossum (python.org/~guido)

On 12/29/2015 2:40 PM, Fred Drake wrote:

On Tue, Dec 29, 2015 at 1:27 PM, Facundo Batista wrote:

...

I was reading PEP 257 and it says that all public methods from a class (including __init__) should have a docstring.

Why __init__?

It's behaviour is well defined (inits the instance), and the initialization parameters should be described in the class' docstring itself, right?

__init__ is not always the only constructor for a class; each constructor's arguments should be documented as part of the constructor.

I agree. >>> help(Someclass) first gives the class docstring, which should explain what the class is about, and then each method, with signature and docstring. The explanation of signatures for __new__, __init__, and any other constructor methods should follow the name and signature of the method. -- Terry Jan Reedy