5 ms·

The downside is that this assumes a "why" exists. Codebases are often evolved rather than designed, and just are the way they are without persistent reasons for

The downside is that this assumes a "why" exists. Codebases are often evolved rather than designed, and just are the way they are without persistent reasons for things. A common reason would be "because it was this other way before." Imagine all the stuff that's probably in MS office, for which the reason is totally lost. There were reasons, but they're not really retrievable.

GrinningFool 8y ago
> Codebases are often evolved rather than designed, and just are the way they are without persistent reasons for things. A common reason would be "because it was this other way before." Yes and no, I think. Codebases represent a collection of point-in-time decisions, and each one of those decisions had a reason. There's always a 'why' even if it's not captured. > Imagine all the stuff that's probably in MS office, for which the reason is totally lost. There were reasons, but they're not really retrievable. True - and that's Really Bad. That means you're stuck not able to improve or change certain things, because you don't know why they were done that way - and when you have a userbase the size of Office, you can't just say 'f it' and break things - at least not lightly, as a code-level decision.
- throwawayjava 8y ago
  The worst "why?" answers often go like this: 1. Green field+0 years: This particular portion of the system was designed in this way as a cargo cult. 2. Green field+2 years: Because that portion of the system was designed in that way, we had to modify this other portion of the system to achieve X. 3. Green field+3 years: Because of the change in 2, and this new constraint Y, we had to make this other change in a third portion of the system. 5. Green field+(3 to N) years: repeat steps 2 and 3. 6. Green field+N+M years: Wow 5 (or previous 6) has created a mess and exposed a serious architectural flaw from step 1 or previous 6. All of the logic in the various iterations of 2+3 are refactored as best as possible. So, the "why" basically grounds out in "the refactoring we could afford to do in order to correct a mess that resulted from a cargo cult or previous refactoring of even older cargo cult". Is that "why" functionally helpful? Usually not for me -- in either case, I can't really assume a lot and I have to proceed with laborious "just watch what the code does" debugging/logging that I would've done without the "why?". But this is probably a ymmv situation.
  - sli 8y ago
    The worst why that I regularly hear is, "the client changed their mind and it's the best we could do." Which, of course, has two negative implications. Not just one.
    - throwawayjava 8y ago
      Yes, that's the root cause of 2+3.
curun1r 8y ago
This is why a test suite is so important. There's no better source of why that a developer who is new to the codebase can turn to. Documentation is likely out of date and pestering the original developer with questions takes both developers' time and is often not possible in cases where the original developer has moved on or forgotten the why. But tests show all the use cases that the original developer thought were important.
- slededit 8y ago
  Test suites don't really explain the "why". The worst is having a hundred tests and every one of them verifying incorrect behavior - I've seen it happen.
slededit 8y ago
Microsoft keeps a meticulous record of their code going back to the 90s. You start having to use older tools past 2000 but the change logs and bug databases are all there. Of course every once in a while you see the super helpful commit log "fix bugs". Some of those are mine and I've even burned myself in the past.
majormajor 8y ago
This is the same problem as "why aren't the docs up to date" and asking for the "why" is going to break down in the same place. I think there might be ways to mostly sidestep this, though. Docs that look more like changelogs than "docs." Store them reverse chronologically so someone new can either look back at recent history or try to jump in to when a particular feature was originally added. Lean in to there being a series of "whys" for the code.
hinkley 8y ago
That’s what annotate is for. You can see the layers of sediment and work out the story.

GrinningFool 8y ago

> Codebases are often evolved rather than designed, and just are the way they are without persistent reasons for things. A common reason would be "because it was this other way before." Yes and no, I think. Codebases represent a collection of point-in-time decisions, and each one of those decisions had a reason. There's always a 'why' even if it's not captured. > Imagine all the stuff that's probably in MS office, for which the reason is totally lost. There were reasons, but they're not really retrievable. True - and that's Really Bad. That means you're stuck not able to improve or change certain things, because you don't know why they were done that way - and when you have a userbase the size of Office, you can't just say 'f it' and break things - at least not lightly, as a code-level decision.

throwawayjava 8y ago
The worst "why?" answers often go like this: 1. Green field+0 years: This particular portion of the system was designed in this way as a cargo cult. 2. Green field+2 years: Because that portion of the system was designed in that way, we had to modify this other portion of the system to achieve X. 3. Green field+3 years: Because of the change in 2, and this new constraint Y, we had to make this other change in a third portion of the system. 5. Green field+(3 to N) years: repeat steps 2 and 3. 6. Green field+N+M years: Wow 5 (or previous 6) has created a mess and exposed a serious architectural flaw from step 1 or previous 6. All of the logic in the various iterations of 2+3 are refactored as best as possible. So, the "why" basically grounds out in "the refactoring we could afford to do in order to correct a mess that resulted from a cargo cult or previous refactoring of even older cargo cult". Is that "why" functionally helpful? Usually not for me -- in either case, I can't really assume a lot and I have to proceed with laborious "just watch what the code does" debugging/logging that I would've done without the "why?". But this is probably a ymmv situation.
- sli 8y ago
  The worst why that I regularly hear is, "the client changed their mind and it's the best we could do." Which, of course, has two negative implications. Not just one.
  - throwawayjava 8y ago
    Yes, that's the root cause of 2+3.

curun1r 8y ago

This is why a test suite is so important. There's no better source of why that a developer who is new to the codebase can turn to. Documentation is likely out of date and pestering the original developer with questions takes both developers' time and is often not possible in cases where the original developer has moved on or forgotten the why. But tests show all the use cases that the original developer thought were important.

slededit 8y ago
Test suites don't really explain the "why". The worst is having a hundred tests and every one of them verifying incorrect behavior - I've seen it happen.

slededit 8y ago

Microsoft keeps a meticulous record of their code going back to the 90s. You start having to use older tools past 2000 but the change logs and bug databases are all there. Of course every once in a while you see the super helpful commit log "fix bugs". Some of those are mine and I've even burned myself in the past.

majormajor 8y ago

This is the same problem as "why aren't the docs up to date" and asking for the "why" is going to break down in the same place. I think there might be ways to mostly sidestep this, though. Docs that look more like changelogs than "docs." Store them reverse chronologically so someone new can either look back at recent history or try to jump in to when a particular feature was originally added. Lean in to there being a series of "whys" for the code.

hinkley 8y ago

That’s what annotate is for. You can see the layers of sediment and work out the story.