Add namespace conventions #2
Conversation
README.md
Outdated
| <sup>[[link](#commonly-used-namespaces)]</sup> | ||
|
|
||
| * <a name="common-namespace-segments"></a> | ||
| Prefer these abbreviations for common namespace segments used inside services: |
There was a problem hiding this comment.
that's squad-wise. a discussion happened about this and I think we didn't get to a company-wide conclusion
There was a problem hiding this comment.
The idea of this PR is to try to reach a company-wide conclusion. (even if the conclusion is that each squad should decide it)
There was a problem hiding this comment.
I'm against the l.foo/m.bar proposal.
In the services where we've tried to follow the Sierra convention, when there was no ambiguity we used just the last part of the namespace like:
[scatterbrain.controller :as controller]
[scatterbrain.logic.discovery :as discovery]
[scatterbrain.logic.aggregation :as aggregation]
When there is ambiguity, we include previous segments to disambiguate:
[metapod.db.datomic.transaction :as datomic.transaction]
[metapod.logic.transaction :as logic.transaction]
I think this is simpler and easier to remember than taking a prefix of a subsegment of the path as proposed above, and IIRC closer to Sierra's description.
There was a problem hiding this comment.
Logic, Models and Controllers are pretty well understood units within all services, so we thought shortcutting it could improve the readability of the code.
We could submit this point to a vote. For the moment I can withdraw it for the sake of pushing the other points forward.
There was a problem hiding this comment.
Another issue: namespaces are very often repeated within logic, controllers, models and db.datomic. Saying some-name instead of l.some-name or logic.some-name might leave the reader wondering from each namespace some-name came from.
Therefore, I think we should make a rule to always use l.some-name or always logic.some-name and never some-name when referring to these namespaces.
README.md
Outdated
| * <a name="stuart-sierra-namespace-guideline"></a> | ||
| Adopt [Stuart Sierra's namespace guidelines](https://stuartsierra.com/2015/05/10/clojure-namespace-aliases) | ||
| unless there is a strong reason not to do so or this style guide says otherwise. | ||
| <sup>[[link](#stuart-sierra-namespace-guideline)]</sup> |
There was a problem hiding this comment.
👍 for Stuart Sierra's namespace guidelines.
There was a problem hiding this comment.
Make it clear the ultimate convention consistency boundary is a service, so avoid mixing aliasing policies in the same service at all costs.
| <sup>[[link](#4-positional-fn-params-limit)]</sup> | ||
|
|
||
| * <a name="forward-references"></a> | ||
| Avoid forward references. They are occasionally necessary, but such occasions |
README.md
Outdated
| * <a name="stuart-sierra-namespace-guideline"></a> | ||
| Adopt [Stuart Sierra's namespace guidelines](https://stuartsierra.com/2015/05/10/clojure-namespace-aliases) | ||
| unless there is a strong reason not to do so or this style guide says otherwise. | ||
| <sup>[[link](#stuart-sierra-namespace-guideline)]</sup> |
There was a problem hiding this comment.
Make it clear the ultimate convention consistency boundary is a service, so avoid mixing aliasing policies in the same service at all costs.
README.md
Outdated
| <sup>[[link](#stuart-sierra-namespace-guideline)]</sup> | ||
|
|
||
| * <a name="commonly-used-namespaces"></a> | ||
| Keep commonly used namespace abbreviations to maintain consistency between services, such as: |
There was a problem hiding this comment.
This such as is opening a huge door for inconsistent styles to creep in. If we want a whitelist of exceptions to the aliasing policy, it should be an extensive list. I personally would prefer to avoid it, and only "whitelist" common namespaces for public libraries such as [schema.core :as s] and [datomic.api :as db].
There was a problem hiding this comment.
I don't feel strongly about listing some of our namespaces here or not. I do feel strongly this should be an exhaustive list, not a such as.
There was a problem hiding this comment.
Sierra's namespace guideline itself allows for some deviation (for well estabilished namespaces in the community or very commonly used namespaces). An extensive whitelist might be impossible to maintain, but maybe there is no harm in trying. The ones I listed here were the ones that came up during the discussion with the Bills team, but others could be added as well in a per need basis.
README.md
Outdated
| <sup>[[link](#commonly-used-namespaces)]</sup> | ||
|
|
||
| * <a name="common-namespace-segments"></a> | ||
| Prefer these abbreviations for common namespace segments used inside services: |
There was a problem hiding this comment.
I'm against the l.foo/m.bar proposal.
In the services where we've tried to follow the Sierra convention, when there was no ambiguity we used just the last part of the namespace like:
[scatterbrain.controller :as controller]
[scatterbrain.logic.discovery :as discovery]
[scatterbrain.logic.aggregation :as aggregation]
When there is ambiguity, we include previous segments to disambiguate:
[metapod.db.datomic.transaction :as datomic.transaction]
[metapod.logic.transaction :as logic.transaction]
I think this is simpler and easier to remember than taking a prefix of a subsegment of the path as proposed above, and IIRC closer to Sierra's description.
No description provided.