6 ms·

To be honest, most of these things can happen for poorly documented large codebase. I work on academic research project that have docs that tells you basically

To be honest, most of these things can happen for poorly documented large codebase. I work on academic research project that have docs that tells you basically that the code is self documented. And give one or two pages about configuring CMake and build the project and another page on how to benchmark the throughout. But the internal quirks and the expected convention you will need to figure it on your own. New people contributing usually reinvent many things and change global configuration because they don't know they can use something already there. Ironically indexing the codebase and ask LLM questions about specific things is the best thing you can do. Because the only 3 people who you can ask left the project or are busy and will reply within a week.

nosianu 1y ago
> most of these things can happen for poorly documented large codebase. Documentation does not help beyond a point. Nobody reads the documentation repeatedly, which would be needed. When you keep working on a project, and you need a new function, you would need to check or remember every single time that such a function already exists or might exist somewhere. You may have found it when you read the docs months ago, but since you had no need for that function at the time your brain just dismissed it and tossed that knowledge out. For example, I had a well-documented utils/ folder with just a few useful modules, but they kept getting reimplemented by various programmers. I did not fault them, they would have had to remember every single time they needed some utility to first check that folder. All while keeping up that diligence forever, and while working on a number of projects. It is just too hard. Most of the time you would not find what you need, so most of the time that extra check would be a waste. Even the most diligent person would at some point reimplement something that already exists, no matter how well-documented it is. It's about that extra search step itself. The closer you want 100% perfection you get exponentially increasing effort. So we have some duplication, not a big deal. Overall architectural quality is more important than squeezing out those last not really important few percent of perfection.
- yunohn 1y ago
  I agree with you completely, but also posit that this is exactly what agentic LLMs should solve? Claude code’s Plan mode kind of does this research before coding - but tbf the Search tool seemingly fails half the time with 0 results and it gets confused and then reimplements too…
- JoRyGu 1y ago
  I'm sorry, but this is selling good engineers very short. If you didn't nest your utils folder 8 folders deep, it seems pretty obvious that one should check the utils folder before writing another utility function. This stuff should also be caught in code reviews. Maybe the new guy didn't know that util function existed, but surely you did when you reviewed their MR? Obviously mistakes like that can happen, but I've found that to be the exception rather than the rule, even in some of the gnarlier codebases I've worked in.
  - staunton 1y ago
    > should also be caught in code reviews Assuming they even have code reviews - in your experience, in a situation where the person writing the code didn't check if it already exists, the reviewer will check that and then tell them to delete their already finished implementation and use that existing thing?
  - wheybags 1y ago
    I wouldn't say you should explicitly check, necessarily. More like, you go to implement the widget and when you open the appropriate file to get started, it's already there.
- michaelsalim 1y ago
  I for one think that this discipline is what separates a good developer from being a good engineer. This kind of rigorous process is the kind of thing that I'd expect from most devs but is sadly missing most of the time.
- globnomulous 1y ago
  In my experience, the usefulness of documentation in code declines as familiarity with a codebase increases. The result: people ignore it; it becomes outdated; now it's debt. Similarly, non-intralinear documentation (documentation that isn't in the code) tends to grow with a codebase. Meanwhile, the codebase changes, personnel change, and more and more of the documentation beco.ed noise, a historical artifact of solving problems that either no longer exist or can no longer be solved the same way. That being said, good documentation is worth its weight in gold and supports the overall health and quality of a codebase/project. Open-source projects that succeed often seem to have unusually strong, disciplined documentation practices. Maybe that's just a by-product of engineering discipline, but I don't think it is -- at least not entirely.
godelski 1y ago
> docs that tells you basically that the code is self documented Anytime someone tells me the code is self-documented I hear "there's no documentation." The most common programmer's footgun I don't have time to document | ^ v | Spends lots of time trying to understand code We constantly say we don't have time to document the code. So instead we spend all our time reading code and trying to figure out what it does, to the minimal amount of understanding needed to implement whatever thing we need to implement. This, of course, itself is naive because you can't know what the minimal necessary information is without knowing something about the whole codebase. Which is also why institutional knowledge is so important and why it is also weird that we'd rather have pay raises through switching companies than through internal raises. That's like trying to fix the damage from the footgun with a footgun.
- aspenmayer 1y ago
  > why it is also weird that we'd rather have pay raises through switching companies than through internal raises How does the saying go, something like “show me the incentives and I’ll show you the outcome?” > That's like trying to fix the damage from the footgun with a footgun. If you value your money/time/etc, wouldn't the best way to fix the damage from footguns be by preventing the damage to you in the first place by not being there if/when it goes off? I think your point is well put, I’m just trying to follow your reasoning to a conclusion logical to me, though I don't know if mine is the most helpful framing. I didn’t pick the footgun metaphor, but it is a somewhat useful model here for explaining why people may act the way they do.
  - ffsm8 1y ago
    The other thing about documentation is that it inevitably goes stale. So the question becomes: is no documentation better or documentation that can be - potentially - entirely out of date, misleading or subtly wrong, because eg they documented the desired behavior vs actual behavior (or vice versa). I'm generally pro documentation, I'm just fully aware that internal documentation the devs need to write themselves and for themselves... Very rarely gets treated with enough respect to be trustworthy. So what it comes down to is one person spearheading the efforts for docs while the rest of the team constantly "forgets" it, until they decide it's not worth the effort as soon as the driving force either changes teams or gave up themself.
rekabis 1y ago
> I work on academic research project that have docs that tells you basically that the code is self documented. Oh, that is just evil.

nosianu 1y ago

> most of these things can happen for poorly documented large codebase. Documentation does not help beyond a point. Nobody reads the documentation repeatedly, which would be needed. When you keep working on a project, and you need a new function, you would need to check or remember every single time that such a function already exists or might exist somewhere. You may have found it when you read the docs months ago, but since you had no need for that function at the time your brain just dismissed it and tossed that knowledge out. For example, I had a well-documented utils/ folder with just a few useful modules, but they kept getting reimplemented by various programmers. I did not fault them, they would have had to remember every single time they needed some utility to first check that folder. All while keeping up that diligence forever, and while working on a number of projects. It is just too hard. Most of the time you would not find what you need, so most of the time that extra check would be a waste. Even the most diligent person would at some point reimplement something that already exists, no matter how well-documented it is. It's about that extra search step itself. The closer you want 100% perfection you get exponentially increasing effort. So we have some duplication, not a big deal. Overall architectural quality is more important than squeezing out those last not really important few percent of perfection.

yunohn 1y ago
I agree with you completely, but also posit that this is exactly what agentic LLMs should solve? Claude code’s Plan mode kind of does this research before coding - but tbf the Search tool seemingly fails half the time with 0 results and it gets confused and then reimplements too…
JoRyGu 1y ago
I'm sorry, but this is selling good engineers very short. If you didn't nest your utils folder 8 folders deep, it seems pretty obvious that one should check the utils folder before writing another utility function. This stuff should also be caught in code reviews. Maybe the new guy didn't know that util function existed, but surely you did when you reviewed their MR? Obviously mistakes like that can happen, but I've found that to be the exception rather than the rule, even in some of the gnarlier codebases I've worked in.
- staunton 1y ago
  > should also be caught in code reviews Assuming they even have code reviews - in your experience, in a situation where the person writing the code didn't check if it already exists, the reviewer will check that and then tell them to delete their already finished implementation and use that existing thing?
- wheybags 1y ago
  I wouldn't say you should explicitly check, necessarily. More like, you go to implement the widget and when you open the appropriate file to get started, it's already there.
michaelsalim 1y ago
I for one think that this discipline is what separates a good developer from being a good engineer. This kind of rigorous process is the kind of thing that I'd expect from most devs but is sadly missing most of the time.
globnomulous 1y ago
In my experience, the usefulness of documentation in code declines as familiarity with a codebase increases. The result: people ignore it; it becomes outdated; now it's debt. Similarly, non-intralinear documentation (documentation that isn't in the code) tends to grow with a codebase. Meanwhile, the codebase changes, personnel change, and more and more of the documentation beco.ed noise, a historical artifact of solving problems that either no longer exist or can no longer be solved the same way. That being said, good documentation is worth its weight in gold and supports the overall health and quality of a codebase/project. Open-source projects that succeed often seem to have unusually strong, disciplined documentation practices. Maybe that's just a by-product of engineering discipline, but I don't think it is -- at least not entirely.

godelski 1y ago

> docs that tells you basically that the code is self documented Anytime someone tells me the code is self-documented I hear "there's no documentation." The most common programmer's footgun I don't have time to document | ^ v | Spends lots of time trying to understand code We constantly say we don't have time to document the code. So instead we spend all our time reading code and trying to figure out what it does, to the minimal amount of understanding needed to implement whatever thing we need to implement. This, of course, itself is naive because you can't know what the minimal necessary information is without knowing something about the whole codebase. Which is also why institutional knowledge is so important and why it is also weird that we'd rather have pay raises through switching companies than through internal raises. That's like trying to fix the damage from the footgun with a footgun.

aspenmayer 1y ago
> why it is also weird that we'd rather have pay raises through switching companies than through internal raises How does the saying go, something like “show me the incentives and I’ll show you the outcome?” > That's like trying to fix the damage from the footgun with a footgun. If you value your money/time/etc, wouldn't the best way to fix the damage from footguns be by preventing the damage to you in the first place by not being there if/when it goes off? I think your point is well put, I’m just trying to follow your reasoning to a conclusion logical to me, though I don't know if mine is the most helpful framing. I didn’t pick the footgun metaphor, but it is a somewhat useful model here for explaining why people may act the way they do.
- ffsm8 1y ago
  The other thing about documentation is that it inevitably goes stale. So the question becomes: is no documentation better or documentation that can be - potentially - entirely out of date, misleading or subtly wrong, because eg they documented the desired behavior vs actual behavior (or vice versa). I'm generally pro documentation, I'm just fully aware that internal documentation the devs need to write themselves and for themselves... Very rarely gets treated with enough respect to be trustworthy. So what it comes down to is one person spearheading the efforts for docs while the rest of the team constantly "forgets" it, until they decide it's not worth the effort as soon as the driving force either changes teams or gave up themself.

rekabis 1y ago

> I work on academic research project that have docs that tells you basically that the code is self documented. Oh, that is just evil.