namespace and require naming

Idiomatic clojure uses aliases to require additional namespaces into the current namespace

Alias names can provide context as to the purpose of the required namespace, making the overall code easier to comprehend.

(ns current.namespace
  (:require [another.namespace.service :as service])) 

The more abstract/general the function names are, the more clarity can be given with an :as alias. The name chosen for the alias should describe the overal purpose of the library functions where possible

Simple examples:

clojure.string :as string will give context that functions are working on string type values

SUT is a common acronym from the software testing & TDD community, although not so common outside. Using the last name of the namespace as an alias is typically more meaningful (assuming meaningful namespace names are chosen)

refer and refer all

When function names are interned from another library its not obvious where a function comes within the body of the code, without jumping to the namespace definition or jumping to the function definition in the required library.

Using :refer [fn-name] if the library included is the main focus of the namespace (e.g. clojure.test, compojure.api, ...)

:refer :all compounds the confusion of where functions come from, as it interns all functions from the required library. Interning all functions also increases the risk of conflicting function names.

clj-kondo will warn against using :refer :all which helps encourage a more idiomatic approach

TODO: define other (positive) guidelines for requires and aliases

Exceptional cases

:refer can be used to intern named functions and other vars (named data structures, etc)

:refer should be limited to namespaces where the overall purpose is specifically about the namespace being required, A common example is clojure.test

Refactor / renaming functions

A namespace with directly interned functions can be more of a challenge to refactor, especially when a function from another namespace is renamed.
Static analysis tools should be able to help with this, but can be more complicated for a human to reason about.

Deprecated approaches

use was introduced into the Clojure language before require :refer :all and so examples may still be found. The use function has the same issues as refer all, in that it can bring in too many namespaces and function that may conflict with each other. Avoiding use and refer all will save a lot of time debugging issues as projects grow.

No file, test, or entry point is named. Start by locating the repository's existing namespace and require guidance, then compare it with the aliases, refer/refer-all, exceptions, and deprecated use cases described here. Done means a focused guideline section with the remaining TODO resolved and clear scope for the recommended practices.