I like the practice of leaving REPL examples in docstrings, especially if I can include Python's `doctest` in the test suite.
Wow, this just blew my mind. I usually keep a bunch of ; commented out lines at the bottom of my file so I can still do M-x cider-eval-buffer when I load up for the first time, but this makes so much more sense without having to comment and comment things all the time.
I think programming at the REPL requires a very different mindset from how a lot of us learned initially. The thought of leaving commented code in our codebase is one of those things we're told not to do, but there's a great snippet from one of Stuart Halloway's talks where he mentions "Rich Comments" (pun intended I think).
Rich is apparently known for leaving REPL code inside comment blocks specifically for testing purposes, and as a sort of transcript of the work that was done. [0]
Its a great approach, and one that I've adopted, but it seems wrong at first glance when taken out of the context of a REPL.
[0] https://github.com/clojure/clojure/blame/4ef4b1ed7a2e8bb0aaa...