[v3] Template for Exercises

[cstby]

Rationale

As we write new concept exercises to v3, we can better set up learners for success by changing the exercise template.

Issue

Here is an example of the current template:

(defn armstrong? [num] ;; <- arglist goes here
  ;; your code goes here
)

This creates a few problems:

• Many learners do not remove these comments before turning in their solution.
• Learners get into the habit of writing functions without docstrings.
• Learners are led to believe that the arglist should go on the same line as the function name. Many learners who later try to add docstrings will add them after the function arguments.

Suggestion

I propose the following changes:

• Add a docstring below the function name. This accomplishes a few goals.
  1. Learners become aware of become aware of docstrings.
  2. The template is more representative of idiomatic Clojure.
  3. Learners are exposed to high-quality examples of how docstrings should be formatted and written.
• Remove the single line comment referencing the function argument. Learners who get past the "function" concept will know that arguments are provided here.
• Change "your code goes here" to be more descriptive. Something like "add function body here" or just "function body" more accurately describe what the learner needs to do.

The result woud look something like this:

(defn armstrong?
  "Returns true if `num` is an armstrong number."
  [num]
  ;; function body
  )

[cstby]

@porkostomus @bemself Forgot to tag your two when creating the issue!

[bemself]

@cstby Nice template! I like the docstring addition, I myself also forgot to add docstring in my example script for concept list, I will add it later. thanks a lot for pointing it out.

For other suggestions, I have only one concern, for a fresh starter, before he touches the function concept, he might not know [] is for arglist.

Remove the single line comment referencing the function argument. Learners who get past the "function" concept will know that arguments are provided here.

[bobbicodes]

Totally agree! I always encourage students to prefer docstrings, for these reasons and with the additional benefit that then your library can be consumed by tools like cljdoc :)

[bobbicodes]

Regarding the prerequisite of understanding basic syntax (like arglist), I'm sure that will be covered by a functions exercise, which will likewise depend upon vectors.

That's 2 more concepts right there - I'll go ahead and make issues for them while this is fresh in my mind.