:refer :all

[brettrowberry]

I'm just getting started with Clojure, so this is more a question than a recommendation.

In the :require portion of each of the files it has a :refer :all, like this:

(ns koans.01-equalities
  (:require [koan-engine.core :refer :all]))

I'm using Calva, and it surfaced this warning:
use alias or :refer clj-kondo(refer-all)

Should the code referenced above be changed to the following?

(ns koans.01-equalities
  (:require [koan-engine.core :refer]))

What is the significance of including or omitting the :all?

[samflores]

The :require portion in the ns macro tells the compiler that the namespace being created - in this case koans.01-equalities - will access values from other namespaces. But you'd still need to type the fully qualified name of the variables you're using, e.g.:

(ns koans.01-equalities
  (:require [koan-engine.core]))

(koan-engine.core/meditations ;; <- this would need to be fully qualified
  "We shall contemplate truth by testing reality, via equality"
  (= koan-engine.core/__ true)

So we use the :refer option to "add" external names declarations into the current namespace. In a real-world project is considered good practice to refer only to the symbols you'll actually use from the other namespace, instead of all, to avoid name clashing with some name you declare in the current namespace.

(ns koans.01-equalities
  (:require [koan-engine.core :refer [meditations __]]))  ;; <- refers only to the symbols being used

You could also use an alias in order to prevent the need to type the fully qualified namespace:

(ns koans.01-equalities
  (:require [koan-engine.core :as k]))  ;; <- refers to nothing, but alias the external namespare as "k" 

(k/meditations ;; <- now you can use the alias instead of the full name
  "We shall contemplate truth by testing reality, via equality"
  (= k/__ true)

That's what clj-kondo is complaining about. It's telling you should explicitly refer to the names or use an alias, but I understand that clojure-koans is a learning tool and aims to present the user with an easier-to-read code so you can focus on the koan rather than the boilerplate. Besides, the koan-engine.core namespace is pretty minimal and defines only 4 names, minimizing the chances of name clashing.

I'd simply silence this warning by adding {:linters {:refer-all {:exclude [koan-engine.core]}}} to the linter configuration file.

[trptcolin]

Thanks @samflores for the clear description! Agreed on all counts! Definitely would recommend doing it the way the linter is guiding you for "real" projects.

My only hesitation in moving to (:require [koan-engine.core :refer [meditations __]]) is that newcomers might reasonably assume that they have to fill in that blank too. Aliasing might be OK, as long as we avoided things like k/__ instead of __ which is a bit noisier - but there might be complications requiring changes to clojure-koan-engine (which would be OK only if they're backwards-compatible). If someone's motivated to dig in, I'm happy to review / QA a PR. But I probably won't tackle it anytime soon.

[brettrowberry]

Does this not work (without the __)?
(:require [koan-engine.core :refer [meditations]])

[samflores]

__ is nothing special in the language. It's just a variable defined inside the koan-engine.core namespace. If you don't bring it into this namespace somehow, the compiler will complain that it's not defined.