# Rich Comment Forms
or _Rich Comment Blocks_.
## Origin
_Rich Comment Blocks_ is a term coined in Stuart Halloway's talk, [_Running With Scissors_](https://youtu.be/Qx0-pViyIDU?t=1229).
> These comments are rich because they provide rich detail about the development process and because they were written by a person named Rich.
The [comment](https://github.com/clojure/clojure/blob/35bd89f05f8dc4aec47001ca10fe9163abc02ea6/src/clj/clojure/core.clj#L4735) form in [[Clojure]] is a macro that discards its body, evaluating to `nil`. Following [examples in Clojure's own core library](https://github.com/clojure/clojure/blob/35bd89f05f8dc4aec47001ca10fe9163abc02ea6/src/clj/clojure/zip.clj#L281), it is common practice in Clojure to use `(comment ...)` forms at the end of source files as a scratch area. An editor-connected [[REPL]] can interactively send those forms to the [[REPL]] instead of typing them in by hand at the [[REPL]] prompt. This workflow saves ad-hoc testing sessions as examples rather than losing them when the [[REPL]] exits.
With a little care, these comment blocks can serve a third role as actual tests - rich.
## Implementations
- [cognitect-labs/transcriptor](https://github.com/cognitect-labs/transcriptor)
- [hyperfiddle/rcf](https://github.com/hyperfiddle/rcf)
### hyperfiddle/RCF
#### Example using [[Clojure#Built-in Tooling tools deps tools build and cli CLI|deps.edn]]
Example `deps.edn`
```clojure
{:paths ["src" "resources"]
:deps {org.clojure/clojure {:mvn/version "1.11.1"}}
:aliases
{:env/dev
;; clj -M:env/dev:env/test
{:extra-paths ["dev"]}
:env/test
{:extra-deps {com.hyperfiddle/rcf {:mvn/version "20220405"}}}
;; clojure -X:env/test:test
:test
{:extra-paths ["test"]
:jvm-opts ["-Dhyperfiddle.rcf.generate-tests=true"]
:exec-fn test/run}}}
```
In `dev/user.clj` so tests can be run in a [[REPL]] session.
```clojure
(ns user
(:require [hyperfiddle.rcf]))
(hyperfiddle.rcf/enable!)
```
In `test/test.clj` to run tests in [[CICD]]
```clojure
(ns test
(:require [clojure.test]))
(def default-under-test
'(the-namespace.project-name))
(defn run [{:keys [namespaces]
:or {namespaces default-under-test}}]
(dorun (map require namespaces))
(dorun (map clojure.test/run-tests namespaces)))
```
#### Example using leiningen
Example `project.clj` so RCF tests are run with `lein test`
```clojure
(defproject the-namespace/project-name "0.0.1"
:dependencies [[org.clojure/clojure "1.11.1"]
[com.hyperfiddle/rcf "20220405"]]
:profiles {:test {:jvm-opts ["-Dhyperfiddle.rcf.generate-tests=true"]
;; src contains test forms
:test-paths ["test" "src"]}})
```