5 ms·

When starting to work on a new code base, good folder structure with sub-readme documents in subfolders goes a long way in terms of understanding different piec

by jupp0r 5y ago

When starting to work on a new code base, good folder structure with sub-readme documents in subfolders goes a long way in terms of understanding different pieces. A high level architecture document describing why the project is structured the way it is is also essential. Once I have a mental model of the parts I’m working on in my head, fuzzy keyboard based navigation (cmd + shift + o in vscode) works best for me to jump between parts of the code base, but it admittedly takes some time (a day or two) to get to that point. It gets much harder in projects that are unintuitively structured for historic reasons or because the maintainers never cared to pay attention to this. A good example in my opinion is the Chromium code base where I spent considerable time over the last couple of years while working on an electron app and which has an excellent code navigator at https://cs.chromium.org https://cs.chromium.org.

kitd 5y ago
I've been thinking about this a lot recently since this was posted: https://news.ycombinator.com/item?id=30858311 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.
- NateEag 5y ago
  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.

by jupp0r 5y ago

kitd 5y ago

I've been thinking about this a lot recently since this was posted: https://news.ycombinator.com/item?id=30858311 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.

NateEag 5y ago
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.