3 ms·
I've found that getting to include the narrative is great when you're first writing it, and then for making small changes. But then, when something happens tha
by LukeShu 9y ago
I've found that getting to include the narrative is great when you're first writing it, and then for making small changes. But then, when something happens that changes your perspective on the problem, the structure of the narrative often needs to change substantially, while the structure of the code might not. And suddenly that formerly helpful narrative is a huge piece of legacy cruft that needs to be refactored... to support a few-line change in the actual code.
For that reason, I'm with you in that I try to write doc-comments that inject the narrative.
- taeric 9y agoI'm curious if you have examples of times when the narrative changed dramatically. I have found that it is easy to rat-hole thinking you know the entire structure and starting on the narrative of how you are writing it. I'm convinced most of even Knuth's programs were written a bit more holistically, and then a narrative emerged not necessarily of how the code was written, but how the code could be explained. And really, this is no different than the other abstractions we have at our disposal. It is rare that the original function layout of the system survives for long. Why would you think your initial narrative would?