Comments (6)
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/)
from axelrod.
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...)
from axelrod.
There are no set rules, just guidelines in the PEP, but why would you consider adding a docstring if it conveys no extra information?
from axelrod.
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?
from axelrod.
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!
from axelrod.
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 :)
from axelrod.
Related Issues (20)
- Reorganisation of documentation. HOT 3
- Reorganisation ? of cheating strategies
- Add a citation.cff file HOT 6
- Links to contributing guide broken by docs restructure
- CI failing due to typing issues HOT 3
- Implement asymmetric games HOT 6
- Game classification HOT 4
- Implement abstract games more fully (5.0.0)
- Restructure strategies folder HOT 4
- Documentation for 5.0.0
- Simplify/move the `ResultSet` HOT 1
- Expressing in a formal logical language HOT 2
- You may have missed some details in your code HOT 1
- I couldn't find the strategy submitted by Mauk in the competition for 19th place HOT 2
- If I want to test the first tournament, what should I do based on your code? HOT 2
- Do you know the source code of the first tournament? HOT 2
- axelrod.plot.Plot may be incompatible with recent Pandas udpates HOT 2
- Change the TFT in the first tournament HOT 3
- High-noise Tournament for comparison HOT 1
- Supporting Python 3.12 HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from axelrod.