Thanks for taking the effort to contribute to this project and thanks for taking the effort to read through this document first. It's appreciated.
Be as general as possible, while still being correct.
Prefer named specs over predicates e.g. ::ifn
instead of ifn?
(#76)
Use associative?
instead of map?
or vector?
(#46)
Use ifn?
instead of fn?
(#42)
Use s/alt
inside for arity alternatives in favor of s/or
:
:args (s/alt :infinite (s/cat ...) :finite (s/cat ...))
seqable?
, not seq?
. Sequence
functions compose because they call seq
on their seqable?
argument, not
because they receive or return a seq?
. Don't spec implementation details
such as the difference between ()
and nil
in return values. See
(#45).(s/fdef clojure.core/range
:args (s/alt :infinite (s/cat)
:finite (s/cat :start (s/? number?)
:end number?
:step (s/? number?)))
:ret seqable?)
vs.
(s/fdef clojure.core/range
:args (s/alt :arity-0 (s/cat)
:arity-1-3 (s/cat :n1 (s/? number?)
:n2 number?
:n3 (s/? number?)))
:ret seqable?)
Provide extensive tests for each spec.
A test for an fdef
consists of thee parts:
respeced.test/check
(nice to have)Example:
(deftest interpose-test
;; 1) example based tests for arguments that should be accepted
(is (check-call `interpose [0]))
(is (check-call `interpose [0 [1 1 1]]))
;; 2) generative tests
(check `interpose)
;; 3) example based tests for arguments that should be rejected
(with-instrumentation `interpose
(testing "wrong amount of args"
(is (caught? `interpose (interpose))))
(testing "non-coll arg"
(is (caught? `interpose (interpose 0 0))))))
After writing a new spec, for it to be instrumentable using
speculative.instrument/instrument
, run:
script/update-syms
This will update the file src/speculative/impl/syms.cljc
.
Some functions will not instrumentable on all environments or have no point in
being instrumented (e.g. some?
, str
). In that case you can update the
blacklist(s) in blacklist.edn
.
Some of these guidelines have been inspired by the guidelines in medley.
Can you improve this documentation?Edit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close