code-should-show-its-work.md

This is a random thought, don’t take it very seriously…

Most of our code is declarative. I don’t mean programming paradigms (because in that sense, most code would be imperative). I mean the way we write and organize it.

Adding a new feature usually requires modifying code in many places. Which…

• makes it harder for readers to infer the original author’s intent.
• makes it harder for maintainers to reason, because they have to navigate among different locations, especially when they don’t have an IDE with “Go To Definition” functionality.
• even makes meticulous programmers crazy because sometimes they may spend an unreasonable amount of time deciding where a new class member should go (add it to last, adapt an alphabetical order, or group it around members of a similar functionality?).

For example, adding a timer usually requires three changes:

1. Add a member variable to store the timer handle.
2. Create the timer at the beginning of the parent component’s lifecycle.
3. Dispose the timer at the end of the parent component’s lifecycle.

That’s one reason why vibe coding becomes popular. Nobody like to “go to” in the codebase a lot.

Literate programming comes to the rescue. It *“open-source”*s the thinking process of the author, not just the final result. What if literate programming integrates a model like Git so you can simplify your history?

Or should I call it, “constructive / incremental / iterative programming”?

Code should show its work. Like a math teacher saying "show your work". Maybe I'm just too dumb, but you don't know how desperate I am, seeing "the proof is left as an exercise" when reading a math book.

A similar idea would be AOP by Java folks. Or advices by Emacs Lisp users. They are limited. Most people will add logging by changing the original code (especially when they own it), not creating a new aspect or adding a new advice.

CMake scripts create a build model, but in an imperative way. In this scenario it should be declarative, so you don’t have to traverse all the includes to find all build targets.