Conversation
CONTRIBUTING.md
Outdated
| | 1A | **Minimal indirection** | In order to cope with the cognitive overhead of traversing code, keep relevant code together. | ||
| | 1B | **Only separate what is shared** | If a function is only ever used by one module, it should become part of that module. Likewise for modules used by a package. | ||
| | 1C | **Prefer fewer large modules to many small** | Whenever you import a module, you create a dependency. The less of those there are, the better. That means no modules with just a single class. | ||
| | 1D | **Upward and lateral imports** | A module may reach up and sideways in the package hierarchy, but not down. E.g. `maya\lib.py` may reach `avalon\io.py`, but `io.py` may not reach into `maya`. |
There was a problem hiding this comment.
Should this not be avalon\maya\lib.py?
CONTRIBUTING.md
Outdated
| | 1D | **Upward and lateral imports** | A module may reach up and sideways in the package hierarchy, but not down. E.g. `maya\lib.py` may reach `avalon\io.py`, but `io.py` may not reach into `maya`. | ||
| | 1E | **Shallow dependency tree** | Avoid traversing more than 3 levels anywhere, unless there is good reason. 3 is plenty. | ||
| | 1F | **Group by dependency, not type** | That is, if 6 modules share code, they should share a package. If 12 functions are used by a single module, they should be part of that module. | ||
| | 2 | **No Subjective Code** | To avoid bikeshedding, avoid submitting code that without a right nor wrong answer. Sometimes, there's a missing space or underscore somewhere |
There was a problem hiding this comment.
Sometimes, there's a missing space or underscore somewhere
What do you mean with this?
There was a problem hiding this comment.
.. or missing dot at the end of line. :D
There was a problem hiding this comment.
Haha, oh no. Yes I was struggling with that one, looks like I forgot to finish.
Not sure how to phrase it; I'd like to avoid PRs that cannot be reviewed. Where opinion A is equal to opinion B. But it's hard to know what's subjective.. any ideas?
There was a problem hiding this comment.
Is it not just a matter of having a goal with the PR?
If a PR doesn't have a right or wrong answer then it probably doesn't have a goal?
The implementation it self can always be discussed and I'm sure as long as the goal gets archived nobody will that strongly about how its done.
There was a problem hiding this comment.
Yeah, let's try that.
|
Allright, let's start with this. I've added issue templates with these as well. Anything else come to mind, either comment here or add to the CONTRIBUTION file. It isn't as visible as I'd like, but at least now we've got something to point at for guidance. |
3 participants
Hi everyone,
In light of a recent PR (#414) and follow-up discussions in private, I thought it would be a good idea to establish a set of guidelines for the project so we all know what to expect and can avoid PRs getting closed moving forwards.
I've added the few I can think of, but they are rough, some can be made more clear and some are likely missing. Have a gander and let me know what you agree with, disagree with and would like to see added.
The diff below doens't do Markdown much justice, find a formatted copy here: