Discovery Coding

Someone said on HN a while back that this sort of approach is the most sensible, because any design doc is just an incomplete abstraction until you get in the weeds to see where all the tricky parts are. Programming is literally writing plans for a computer to do a thing, so writing a document about everything you need to write the plan is an exercise in frustration. And if you DO spend a lot of time making a perfect document, you've put in far more work than simply hacking around a bit to explore the problem space. Because only by fully exploring a problem can you confidently estimate how long it will take to write the real code. Often times after the first draft I just need to clean things up a bit or only half complete a bad solution before improving it. Yes, there are times you need to sit and have a think first, but less often than you might imagine.

Of course, at a certain scale and team size a tedious document IS the fastest way to do things... but god help you if you work on a shared code base like that.

I've always thought the rigid TDD approach and similar anti-coding styles really lend themselves to people that would rather not be programming. Or at least have a touch of the OCD and can't stand to not have a unit test for every line of code. Because it really is a lot more work both up front and in maintenance to live that way.

Cyber-paper is cheap, so don't be afraid to write some extra lines on it.

I think it's a dangerous philosophy for professional work. You know what happens to code that works? It ships.

If you code out a solution to the problem in order to discover the problem space, I think the idea here is that you then can go back and write a better solution that accounts for all of the stuff you discovered via refactoring and whatnot. But you're not going to do that refactoring. You're going to ship it. Because it works and you don't know of any problems with it. Are there scaling problems? Probably, you haven't run into any yet. Does your solution fit whatever requirements other interested parties might have? Who knows! We didn't do any designing or thinking about the problem yet.

I am an avid discovery coder and was actually day dreaming an outline for a similar article on my way home on the bus today. I think this is an extremely important concept at all levels of engineering and something we all need to adopt at one point or another in our careers / practice.

I think it follows a few topics, "the art of the POC/Spike" or just exploratory coding. These things give us a tangible hands on approach for understanding the codebase, and I think lend to better empathy and understanding of a software system and less rash criticisms of projects that may be unfamiliar.

This is particularly relevant to me right now as I am discovery coding a fairly large project at my company and working with product to lay out design and project planning. Whats difficult to express from my current standing is how the early stages of these types of projects are more milestone / broad based rather than isolated small key pieces. Sure I can spend a week delivering design, architecture, epic, outline docs for all the known and unknown features of the project (and I am). But at the same time I need to discover and test out base case / happy path solutions to the core business problem to more accurately understand the scope of the project.

I think its something I particularly love about being a TL / IC at my company. I have the flexibility and trust to "figure it out" and the working arrangement to provide adequate professional documentation at the appropriate time. I am fortunate to have that buy in from leadership and certainly recognize it as a unique situation.

All that being said:

1. Learn how to effectively isolate and run arbitrary parts of your system for YOUR understanding and learning 2. Make it work, make it right, make it fast. 3. Learn to summarize and document your findings in a suitable fashion for your situation 4. Encourage this throughout your team. Useful in all aspects from bug triage to greenfield work

I’m this but the problem sometimes is I get overwhelmed by the stuff I’m working on. But honestly I wouldn’t do it any other way

One trick I find helpful is to start by coding a subset of the problem with the goal of understanding the structure better. A brute-force solution, a simulation, a visualization of data, etc. And then use the discoveries of that process to do the real planning.

I call this exploratory programming, though my approach aligns more with the article I posted here, than with the Wikipedia definition.

I primarily use this method as a step preceding the actual production-quality implementation. It’s not like a prototype—I don’t throw everything away when I’m done. Instead, I extract the valuable parts: the learned concepts, the finished algorithms, and the relevant functions or classes. Unit tests are often written as part of setting up the problem, so I lift those out as well.

I’ve greatly enjoyed this approach, particularly in JavaScript&|TypeScript. Typically, I solve the difficult parts in a live environment and extract the solutions when I find them. I used to use my own "live environment" (hedon.js), but I eventually reversed the approach and built an environment around the built-in Node.js REPL (@dusted/debugrepl). I include this, at least during debugging and development builds, allowing me to live-code within a running system while having access to most, if not all, of the already-implemented parts of the program.

This approach lets me iterate at the function-call or expression level rather than following the traditional cycle of modifying code, restarting the program, reestablishing state, and triggering the desired call, something that annoys me to no end for all the obvious reasons.

I believe this is actually where Gen AI tools like Claude.AI come into their own. For example, in the past few weeks we needed to plan a complex integration project with both frontend and backend integrations, dependencies on data provided in backend and frontend, need to send data backwards and forwards from the 3rd party and our backend, etc, and in total probably a half-dozen viable alternative ways of doing it.

Using Claude plus detailed prompting with a lot of contextual business knowledge, it was possible to build a realistic working prototype of each possible approach as separate Git branches and easily demo them within about two days. Doing this also captured multiple hidden constraints aka "gotchas" in the 3rd party APIs.

Building each of these prototypes in the working Java codebase would have been a massive, time-consuming and pointless activity when a decision still needed to be made on which approach to go with. But getting Claude AI to whip up a simplified replica of our business systems using realistic interfaces and then integrate the 3rd party was super-easy. Generating alternative variants was as simple as running a script to consolidate the source files and getting Claude to generate the new variant, almost without any coding needed.

And because this prototype was built in few html and js files and run using node js, there is literally zero possibility of it becoming part of the production codebase.

I really appreciate this essay.

I've never been a [traditional] artist, but I reckon that those working in the arts, and even areas of the programming world where experimentation is more fundamental (indie game development, perhaps?), would intuit the importance of discovery coding.

Even when you're writing code for hairy business problems with huge numbers of constraints and edge cases, it's entirely possible to support programmers that prefer discovery coding. The key is fast iteration loops. The ability to run the entire application, and all of its dependencies, locally on your own machine. In my opinion, that's the biggest line in the sand. Once your program has to be deployed to a testing environment in order to be tested, it becomes an order of magnitude harder to use a debugger, or intercept network traffic, or inspect profilers, or do test driven development. It's like sketching someone with a pencil and eraser, but there are 5-10 second delays between when you remove your pencil and when the line appears.

Unfortunately, it seems like many big tech companies, even that would seem to use very modern development tooling otherwise, still tend to make local development a second class citizen. And so, discovery coders are second class citizens as well.

This reminds me of a tongue-in-cheek phrase we used to use in college.

"Hours of coding can save minutes of planning."

"Discovery Coding" sounds fun, but be careful with your time!

Reminds me of the alleged programming approach of Dr. Joe Armstrong of Erlang fame (RIP): write a program, then rewrite it, then rewrite it, and so on until it's good enough.

That's also how I tend to program, though usually as an accidental consequence of my ADD brain getting distracted, then being entirely dissatisfied with my code (or worse: I was too clever with it and it's indecipherable) when I come back to it, prompting yet another rewrite.

Never thought of it this way, but it makes sense. My default response to probing/planning type questions from business is "uhhh no clue, I have to dive into the code first and find out" precisely because of this.

The actual term for a "discovery writer" is a "pantster" - i.e., you're writing by the seat of your pants - and I think that's a reasonable term to adopt here too.

Confession: I'm a pantster in writing both code and prose. In both cases, coming back and writing a spec (an eng spec in the case of code, a synopsis in the case of prose) is a reasonable thing to do. Structure is good, but the point is that it shouldn't get in the way of actually getting started and making some progress.