Fork me on GitHub
#clojure-spec
<
2021-01-12
>
Alys Brooks22:01:36

is there any guidance on where to start adding specs to an existing project?

Alys Brooks22:01:04

my current strategy is basically to add specs to new code like I do tests. my next step will probably be trying to add specs as I happen to touch other code. however, I'm wondering about more proactive approaches.

seancorfield23:01:54

@actuallyalys_slack I tend to focus on only adding specs where I think it will help me understand the code -- to avoid the temptation to treat Spec like a type system.

seancorfield23:01:59

Common guidance is: write specs for your data structures but don't over-specify them; write specs for functions at "boundaries" (APIs of modules, for example) but don't get carried away. If you over-specify the code, it will be harder to make changes in the future because you may bake in assumptions that don't really hold as invariants over time.

🔥 1
Alys Brooks23:01:26

good point. i'm not as worried about over-specification because instrumentation can always be turned off or specs commented out.

Alys Brooks23:01:31

but there's still a time and mental cost to over-specified specs even so, so that's a good reminder.

Alys Brooks23:01:42

i do think non-boundary specs can be useful because sometimes it's hard to know the exact shape of the data an internal function deals with or tedious to create it for the purpose of REPL experimentation. i guess that falls under "where i think it will help me understand the code"

seancorfield23:01:32

Yup, I recently had to tackle a large part of our code base at work that I hadn't had to work on before and the first thing I did was to spec out some of the data structures, add some function specs, instrument the code and see what broke (and what worked) -- and then evolve the specs until everything worked again and that gave me a good understanding of what the data structures looked like and how the functions transformed them.

🔥 1