Our great sponsors
-
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
-
With that said, my solution in Clojure is to lean heavily on the REPL and on unit tests. It’s often helpful to save REPL sessions to comments. Unit tests should be written in a way that documents your data structures. I also use spec (and more recently malli) both as a form of documentation and validation. Sometimes I put examples in docstrings.
tag / stick into something like https://github.com/djblue/portal makes this problem instantly go away, and I get a whole bunch extra stuff at the same time: https://www.youtube.com/watch?v=gIoadGfm5T8 If you MUST have it codified somewhere, probably the next highest leverage point is to use specs. Typically we do this when you've a single set of data structures that are widely reused (as opposed to, say, a map that's only used between a single SPA component and an API call). I've tried both clojure.spec and Malli. Clojure's spec is satisfactory. Malli's ergonomics and performance are fantastic. https://github.com/metosin/malli
Use assertions for all data requirements inside functions - I use a modified version of https://github.com/ptaoussanis/truss to ensure that I never get NullReference exceptions, and this also helps make functions more self-documenting. Also use this to assert return data.
Use scope-capture to observe the actual data flowing through the system