Atelier Clockwork

Description Informs Structure

Much Like Quantum Mechanics: We Change Things by Observing Them

As the clock ticks down and I attempt to make sure my successors will be able to make use the work I’ve done over the last year, that means I’m writing documentation. The code itself has passable documentation coverage, and Objective-C leads to very verbose code, which hopefully means more obvious functionality. The thing I’ve been documenting is how the entire project fits together.

The interesting thing is: describing the project often makes me refactor in all sorts of small ways. All of them were things like labeling ‘fetchPrices.js’ to ‘priceRegressionTester’ to make the purpose of that file obvious. I missed that the first time around because the price tester started out as a generic test, but eventually became a regression testing suite as I tested against a much larger data set.

None of the code changes are huge, but by and large it’s making the code slightly better. If nothing else it’s making it conform to a more coherent mental model which will hopefully help the future maintainers.