Description
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.
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 must be a vector, leading them to write solutions that work with vectors only.
Another example:
(deftest six
(is (= [2, 3] (prime-factors/of 6))))
New learners may believe that the output should be a vector, when in fact, it could also be a list.
Previous PR/issue: #227