Tldr; 67% of time spent on a project is maintenance, and 60% of time spent on existing code (ie when doing said maintenance) is spent on understanding it. For a reasonable sized project, that is man-months of effort and a huge cognitive burden.
I've begun to wonder whether tools like literate programming, that have been with us for decades, are only just now starting to look value for money. They require an upfront investment, but you win it back in spades in not having the massive technical debt of painfully unnavigable code that hampers even basic development tasks.
I go with literate programming because I don't think basic documentation cuts it. LP puts code description front and centre and is much easier to keep in step with the source output as a result. Basic documentation by contrast relies on goodwill and trust, and is vulnerable to time pressures.
I think something akin to literate programming is a huge win for heavily-maintained tools.
The trick is that most tools aren't heavily used at all, and thus the large amount of time it takes to build in a more literate style winds up being largely wasted.
At least, that's how it looks from where I sit, as an idealist who loves readable code and plain-text, version-controlled literate-style documentation.
Comments
I've been thinking about this a lot recently since this was posted:
https://news.ycombinator.com/item?id=30858311
Tldr; 67% of time spent on a project is maintenance, and 60% of time spent on existing code (ie when doing said maintenance) is spent on understanding it. For a reasonable sized project, that is man-months of effort and a huge cognitive burden.
I've begun to wonder whether tools like literate programming, that have been with us for decades, are only just now starting to look value for money. They require an upfront investment, but you win it back in spades in not having the massive technical debt of painfully unnavigable code that hampers even basic development tasks.
I go with literate programming because I don't think basic documentation cuts it. LP puts code description front and centre and is much easier to keep in step with the source output as a result. Basic documentation by contrast relies on goodwill and trust, and is vulnerable to time pressures.
I think something akin to literate programming is a huge win for heavily-maintained tools.
The trick is that most tools aren't heavily used at all, and thus the large amount of time it takes to build in a more literate style winds up being largely wasted.
At least, that's how it looks from where I sit, as an idealist who loves readable code and plain-text, version-controlled literate-style documentation.