Clarify `ns` form rules
camsaul opened this issue · 3 comments
There are a handful of things that aren't covered in the Namespace Declaration section, that are mentioned in Stuart Sierra's How To ns
style guide. It's probably good to have opinions on these things one way or another:
-
Should one use vectors or lists for
:refer
and:exclude
, e.g.[clojure.string :refer [blank? capitalize ends-with?]]
or[clojure.string :refer (blank? capitalize ends-with?)]
? I think the "vectors" is a pretty uncontroversial here, but this is not mentioned in the style guide -
Should we sort
:exclude
d symbols, or does it not matter? How tons
suggests sorting them. This style guide suggests sorting:refer
, but says nothing about:exclude
, and there's an unsorted example here. -
Should bare namespaces without
:refer
/:as
/etc. still be wrapped in square brackets? How tons
says yes, because it makes visual scanning and sorting easier. This style guide doesn't say either way and there are no relevant examples here -
Should prefix lists in
:import
be a vector or a list? How tons
suggests a list. This style guide does not say anything about this, altho there are a few examples that use vectors. -
How to
ns
also suggests always using prefix lists forimports
, even for just one class in that package. This style guide doesn't have an opinion either way -- it doesn't say for example "always use prefix lists forimports
" or "do not use prefix lists when importing a single class from a package, but use them for multiple classes from a single package", but examples do seem to be following the latter rule.
It seems to me like the community is generally moving in the direction of How to ns
, and if I had a vote I would just say adopt the rest of the rules in How To ns
wholesale, but I'd rather see alternative rules than no rules at all. If any of these rules aren't things that you don't want to incorporate because of opposing opinions, maybe mentioning the different opinions would be better than leaving the rules out entirely?
I'd be fine to backfill whatever's missing here from "How to ns". PRs welcome (e.g. a PR per bullet point, so it's easier to discuss stuff if there are varying opinions on some topic)!
Agreed.
The only ns
guideline I feel strongly about is the newline after :require
/:import
before the list of nses/classes -- which is a style I really dislike, so I'm happy the guide still says "good" for the format without that newline. With automated ns-sorting tools that retain the newline or no newline layout, the argument for the newline (easier sorting) is somewhat moot, IMO.
I'd certainly like to see those "missing" guidelines added here. There are probably other things in Sierra's "Do's and Don'ts" series that might be worth incorporating into the guide...
Is anyone volunteering to submit up to five PRs for this? (one for each bullet point)