Add section on documentation #19
Conversation
![accesslint[bot]](https://avatars.githubusercontent.com/in/1502?s=60&v=4){kind=small}
ewanjones
force-pushed
the
documentation
branch
4 times, most recently
from
067d815
to
832a2ae
Compare
ewanjones
force-pushed
the
documentation
branch
from
832a2ae
to
c6166be
Compare
There was a problem hiding this comment.
Looking nice.
A general thought - some of our architectural guidance might be interim / very specific to our project. For example we might talk about the comms module being a special case that doesn't fit into the layers at the moment. It feels to me like that stuff shouldn't be publicly available, the way this style guide is. Not sure what is the best answer is to this.
|
|
||
| ### Docstrings | ||
|
|
||
| Important classes and modules which are intended to be used throughout the whole codebase |
There was a problem hiding this comment.
Might be worth having some guidance about when to include a big docstring and when it's okay to have less. Personally I think it should be possible to look at every function in isolation and have a good understanding about its inputs, outputs and what it's trying to achieve - but that doesn't always mean it needs a docstring.
There was a problem hiding this comment.
I'm not convinced we need this section - I think the gist could be captured with an extra sentence in the existing section on docstrings and comments.
Plus, do we really want to suggest such a verbose docstring template - seem OTT to me. Is there an example of a docstring like this already?
There was a problem hiding this comment.
@seddonym I agree with you, a lot of small functions wouldn't need documenting, I can make that clearer.
@codeinthehole Most of the sections are suggested, but it was more a way of having a defined layout. I tried to ask questions that could help peopler structure their code more cleanly.
|
|
||
| ### READMEs | ||
|
|
||
| Each directory within the domain layer should be modular and intuitive to use. A README can |
There was a problem hiding this comment.
| Each directory within the domain layer should be modular and intuitive to use. A README can | |
| Each package within the domain layer should be well structured and intuitive to use. A README can |
| ### READMEs | ||
|
|
||
| Each directory within the domain layer should be modular and intuitive to use. A README can | ||
| optionally be placed in the root module directory and should detail specifics such as: |
There was a problem hiding this comment.
| optionally be placed in the root module directory and should detail specifics such as: | |
| optionally be placed in the package directory and should detail specifics such as: |
| Each directory within the domain layer should be modular and intuitive to use. A README can | ||
| optionally be placed in the root module directory and should detail specifics such as: | ||
|
|
||
| - How is this module laid out? |
There was a problem hiding this comment.
| - How is this module laid out? | |
| - How is this package laid out? |
|
|
||
| ## Documentation | ||
|
|
||
| ### READMEs |
There was a problem hiding this comment.
| ### READMEs | |
| ### Domain package READMEs |
This section probably belongs in the "General Python" section, next to the existing note on docstrings.
|
|
||
| ### Docstrings | ||
|
|
||
| Important classes and modules which are intended to be used throughout the whole codebase |
There was a problem hiding this comment.
I'm not convinced we need this section - I think the gist could be captured with an extra sentence in the existing section on docstrings and comments.
Plus, do we really want to suggest such a verbose docstring template - seem OTT to me. Is there an example of a docstring like this already?
| - How might someone use it? | ||
| - What are the use cases? | ||
| - How to extend behaviour (e.g. adding a new flow handler) | ||
| - Who to contact if you run into errors |
There was a problem hiding this comment.
I don't think we should be including names of particular developers in the code base. That kind of thing gets out of date. If we want to do something like that, it might make more sense to have it in a google doc.
No description provided.