In general, I try to avoid defining top-level functions which return functions if I can write make the intent clearer using anonymous functions instead.
For example, writing something like this makes me feel clever:
"Returns a function to compute foo of value."
"Does stuff with values."
(map (foo option))
But it’s easier for someone else to read when the closure is created close to where it’s used:
"Returns the foo of value"
(defn computation [option values]
(map #(foo % option))
I allow an exception to this rule when returning functions is part of a repeated pattern. For example, the transducer versions of
filter, and other sequence functions all return functions, but that’s a standard part of the language since Clojure 1.7 so users can be expected to know about it. Occasionally I discover a similar pattern in my own code.
When functions returning functions are not part of a repeated pattern but for some reason I want them anyway, I call them out with a suffix
"Returns a function to compute the foo of a value."