Descriptions and tests may be misleading regarding the type of both input and expected values

[tasxatzial]

I'm opening a new issue to address and discuss two related, previously unresolved issues.

Problem 1

Exercise descriptions will usually mention words that mislead new learners as to what type of input is expected. Here's an example from https://github.com/exercism/problem-specifications/blob/main/exercises/sublist/description.md

If A = [1, 2, 3] and B = [], then A is a superlist of B

Here, lists are mentioned, but vector notation is used. This is not only confusing but also appears incorrect.

This issue can also manifest in the descriptions of tests if the description is copied from the problem specifications. For example:

(deftest list-equals-itself-test
  (testing "list equals itself"
    (is (= :equal (sublist/classify [1 2 3] [1 2 3])))))

Also, the function name suggests that it accepts lists. Since we can pick whatever function name we want, the naming of the functions won't be discussed here but in another issue where we'll address a template for the tests.

Previous PR/issue: #507 #628

Problem 2

Tests will typically use vectors to check for equality. Example:

(deftest list-equals-itself-test
    (is (= :equal (sublist/classify [1 2 3] [1 2 3]))))

Vectors are used as input arguments here, which may mislead new learners into thinking the input should be a vector.

Another example:

(deftest six
  (is (= [2, 3] (prime-factors/of 6))))

Here, new learners may believe that the output should be a vector.

Previous PR/issue: #227

---

Why do these issues need to be addressed?

Because misleading people about the type of the container goes against the core philosophy of Clojure. We want functions that accept collections and sequences, not just vectors, lists, etc. This is how most Clojure functions work.

As for the type of the output, it does matter, but at the same time, it goes beyond the problem specifications. However, in some exercises, it might be appropriate to require a specific type, such as a lazy sequence, for example, when the exercise asks for the nth prime. Generally, we should let the user decide what the most appropriate type of container is.