[Clojure] Implement new Concept Exercise: `basic-functions`

[bobbicodes]

This issue describes how to implement the basic-functions concept exercise for the Clojure track.

Getting started

Please please please read the docs before starting. Posting PRs without reading these docs will be a lot more frustrating for you during the review cycle, and exhaust Exercism's maintainers' time. So, before diving into the implementation, please read up on the following documents:

• The features of v3.
• Rationale for v3.
• What are concept exercise and how they are structured?

Goal

The goal of this exercise is to teach the student how functions are used in Clojure, as a basic first introduction. More advanced uses will be covered separately.

Things to teach

• defining functions with defn
• docstrings
• arguments
• calling functions

Things not to teach

• anonymous functions
• transducers
• spec
• higher order functions
• multi-arity functions
• variadic functions
• multimethods
• interop

Concepts

• evaluation
• arguments
• parameters
• first-class functions
• pure functions

Prerequisites

• evaluation (REPL)
• vectors
• lists
• sequences
• symbols
• vars
• comments

Resources to refer to

Hints

• Learn Clojure - Functions

After

• Clojure guide - higher order functions

Representer

No special requirements are needed for this exercise.

Analyzer

No special requirements are needed for this exercise.

Implementing

To implement a concept exercise, the following files must be created:

languages
└── clojure
    └── exercises
        └── concept
            └── <SLUG>
                ├── .docs
                |   ├── instructions.md
                |   ├── introduction.md
                |   ├── hints.md
                |   └── after.md (optional)
                ├── .meta
                |   |── design.md
                |   └── Example.clj
                ├── <NAME>.clj
                └── <NAME>_test.clj

Help

If you have any questions while implementing the exercise, please post the questions as comments in this issue.

[ErikSchierboom]

@porkostomus There are quite some things this exercise teaches. I don't know enough about Clojure to be able to judge if this is too much for a 5-10 exercise, but in case things become a bit too complex/bit, it's totally fine to split this up into multiple exercises.

[bobbicodes]

It sure does look like a lot! For a comparison I just went through the Clojurescript Koans section on functions, which covers a good chunk of that, and it took around 10 minutes.

But you're right, we can definitely give a better treatment by refining this further. Variadic and multi-arity functions ought to have their own exercise. So should partial. And Java interop for sure.

I'm thinking it would probably be wise to go easy on the beginner by just making this basic functions, teaching the bare minimum to move forward, and coming back to higher-order functions, etc.

Instead of dumping on them all at once "Here's everything you'll ever need to know about functions"

[ErikSchierboom]

Yep, totally agree with everything you said! 👍

[cstby]

Might be worth separating anonymous functions into a different exercise? I feel there's enough to teach about them to warrant it.

[ErikSchierboom]

I feel there's enough to teach about them to warrant it.

I'd say: go for separate exercises whenever you feel that makes sense.

[bobbicodes]

Sounds reasonable to me. If I'm picturing it right, that would narrow this one down to just describing the defn form and its parts (docstring, args, body). Short and sweet.

[cstby]

Sounds right to me!

As a learner, I wouldn't mind having many small exercises. As long as we're introducing a new concept for each one, I think we should push toward the lower limit of exercise scope. We'll know it when we hit it.

Edit: I mean for concept exercises. I would feel very differently about practice exercises.

[bobbicodes]

Edited this issue to reflect all that. It's also clearer which ones to do next :)

[bemself]

Looks great!

I'd say I learned defn before I know vars, symbols...:-) prerequisites could be shorter I think, e.g. the body could be simple as (+ 1 2) without knowing complex types.

but I understand it depends, when we implement this concept, we might want to put some basic types into use.

[cstby]

I agree about the prerequisites. @porkostomus when in the progression do you see this one? Like @bemself, I was under the impression that functions would be one of the first concepts.

[bobbicodes]

This was right after our discussion in #710 where a few things seemed necessary to explain first, like the vector for the arglist. To me it seems beneficial at this point to already be aware of the difference between lists and vectors, but maybe it's not necessary.

The usual path that I've seen is for the book or course to first cover the data types and basic operators, then teach how to name and compose them. For that reason I chose to err on the side of explaining too much, rather than fail to identify any possible prerequisites. But a great curriculum is one that knows how to sensibly defer what can be filled in later, so I'm pleased to go that way.

[JimLynchCodes]

Hey all, not sure if this is any good but I started building out the exercise for this and opened up a PR for it here: https://github.com/exercism/v3/pull/804

Open to feedback from anyone on it! Thanks! 🙏

[baskeboler]

How about including a simple definition of a predicate? Just to highlight the convention of ending the function name with a ?.

[bemself]

@baskeboler I agree! This is also one of the features Clojure differs from other languages.

[bobbicodes]

This material is to be covered by the basics exercise (#1508). All the effort put into this by everyone is greatly appreciated :)