Make sure each and every method etc has a line of docstring

[drvinceknight]

Even if it's just a simple one liner that basically repeats the name of the function itself.

[langner]

Even if it's just a simple one liner that basically repeats the name of the function itself.

What for? Tricial docstrings have no use. To quote PEP 257:

The one-line docstring should NOT be a "signature" reiterating the function/method parameters (which can be obtained by introspection). Don't do:

def function(a, b):
    """function(a, b) -> list"""

(see https://www.python.org/dev/peps/pep-0257/)

[drvinceknight]

Oh wow: I was not familiar with this (my Sage development has drummed the opposite in to me).

So if a method has a very verbose name this would imply to not write a docstring?

(My apologies to @meatballs for requiring them on a recent pull request...)

[langner]

There are no set rules, just guidelines in the PEP, but why would you consider adding a docstring if it conveys no extra information?

[drvinceknight]

Mainly so that something comes up if anyone types help(<command>). Once I've written up nice documentation (so docs about strategies etc... - planning on using readthedocs), I was hoping to package this so that anyone could set up their own tournament even if they didn't want to contribute new strategies. My thinking was that each and every method should then have a docstring (that's kind of the rules with Sage dev) but if that's not necessary I would much rather prioritise adhering to guidelines. What do you think?

[meatballs]

I've always liked this quote:

“The proper use of comments is to compensate for our failure to express our self in code”
[Clean Code: A Handbook of Agile Software Craftsmanship, Robert C. Martin]

I personally loathe the practice of polluting code with comments. It makes the code harder to navigate and understand. I find the Sage code one of the worst offenders - the ratio of comment to code in any given file must be in the order of 10:1.

There's a reasonable blog entry on the subject here: http://blog.goyello.com/2013/05/17/express-names-in-code-bad-vs-clean/

But - it's one of those areas where a project needs to define its own standards and expectations. I'm possibly at one extreme of the thinking in this area and I'm not the owner of the repository!

[drvinceknight]

I find the Sage code one of the worst offenders - the ratio of comment to code in any given file must be in the order of 10:1.

Yeah I agree with that. It in fact leads to quite confusing documentation. Although in that particular instance it's because of the doctesting paradigm (which I think makes sense for the community).

But - it's one of those areas where a project needs to define its own standards and expectations. I'm possibly at one extreme of the thinking in this area and I'm not the owner of the repository!

Well I'd really like to adhere to PEP guidelines. Let's just close this issue and keep things going as they are and in general keep adhering to PEP :)

I'm certainly learning a lot as I go along so appreciate everything I am learning from you both @langner and @meatballs :)