Clarify ns form rules

[camsaul]

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 :excluded symbols, or does it not matter? How to ns 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 to ns 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 to ns 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 for imports, 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 for imports" 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?

[bbatsov]

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)!

[seancorfield]

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...

[seancorfield]

Is anyone volunteering to submit up to five PRs for this? (one for each bullet point)