Map Clojure Namespaces to Files

A Clojure namespace is the unit you normally load, require, reload, and alias. It plays part of the role a Java package plays, but it is not a class container. A namespace can hold functions, vars, macros, specs, constants, and interop helpers without wrapping them in a class.

The practical rule is simple: a namespace name must line up with the file path that can be found on the classpath.

The hyphen-to-underscore rule is the part Java engineers usually miss. Use hyphens in namespace names when they read well, but store those namespace segments with underscores in file names.

The ns Form Sets the Loading Boundary

Put the namespace declaration at the top of the file. It tells Clojure which namespace receives the definitions in that file and which other namespaces should be available by alias.

1(ns order-service.pricing
2  (:require [clojure.string :as str]))
3
4(defn normalize-code [code]
5  (-> code
6      str/trim
7      str/upper-case))

For this namespace, the normal production file is:

1src/order_service/pricing.clj

Think of :require as closer to Java’s import plus classpath loading. The alias does not copy definitions into the current namespace. It gives you a short, explicit qualifier such as str/trim.

How Loading Finds the File

When Clojure sees (require 'order-service.pricing), it looks for a loadable resource that matches the namespace convention. The diagram below shows the path translation that matters during debugging.

    flowchart TD
	    A["Namespace symbol"] --> B["order-service.pricing"]
	    B --> C["Dots become directories"]
	    C --> D["Hyphens become underscores"]
	    D --> E["Classpath resource"]
	    E --> F["order_service/pricing.clj"]

What to notice: Clojure does not scan every file looking for a matching (ns ...) form. It uses the namespace name to derive a resource path on the classpath. If the path is wrong, require fails before your function definitions matter.

Java Package Instincts That Transfer

Your Java package-navigation habit is useful, but it needs two adjustments.

The biggest design shift is that a namespace should usually describe a coherent set of functions and data transformations, not a single class. For example, order-service.pricing might contain pricing rules, helper functions, and pure calculations. It does not need PricingService, PricingUtils, and PricingCalculator classes just to organize behavior.

Require Aliases Keep Call Sites Clear

Prefer explicit aliases for namespaces you call frequently.

 1(ns order-service.handler
 2  (:require
 3   [order-service.pricing :as pricing]
 4   [order-service.validation :as validation]))
 5
 6(defn handle-price-request [request]
 7  (let [order (:body request)]
 8    (if-let [errors (seq (validation/order-errors order))]
 9      {:status 400
10       :body {:errors errors}}
11      {:status 200
12       :body {:total (pricing/total order)}})))

This is more maintainable than pulling many names into the current namespace with :refer :all. Java developers often like broad imports because IDE navigation can hide the cost. In Clojure, qualified names communicate ownership directly in the code.

Common Loading Failures

Practice

Create src/order_service/pricing.clj and require it from a REPL.

1(ns order-service.pricing)
2
3(defn total [order]
4  (reduce + (map :price (:items order))))

Then evaluate:

1(require '[order-service.pricing :as pricing])
2
3(pricing/total {:items [{:price 12} {:price 8}]})
4;; => 20

If the require fails, debug the path first. If the call fails after require succeeds, debug the var name, argument shape, or namespace reload state.

Knowledge Check