5 ms·

To each their own, I use to enjoy such. I absolutely hate it now. Given a codebase, I want to know the story. Why was the code written, what problem was bei

To each their own, I use to enjoy such. I absolutely hate it now. Given a codebase, I want to know the story. Why was the code written, what problem was being solved, why did they decide to solve it in a specific ways, WHY, WHY, WHY? I need to know the whys. I want the story, I want to know the domains. How is the software layered, can I explore one layer without going into other layers? I don't want to do so with a debugger. I want to do so with a document reader.

dalbasal 8y ago
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.
sorahn 8y ago
A lot of modern IDEs are debuggers too. So now you’re reading the code, in your document reader, but it’s got a bunch of the variables filled in with real values.
adamnemecek 8y ago
These are orthogonal. Yes, why's would be nice but you will never actually get a satisfying answer. Debuggers are I guess the best option.
pjc50 8y ago
This would be nice, but who wants to write the why? If you're lucky, you've got the commit messages and associated bug/work tracker items that explain where the software comes from. I agree there's no substitute for planning documents, but those don't always survive confrontation with the enemy.
zamalek 8y ago
> WHY If a developer doesn't check for a null value, are you really going to head to the documentation to find out why? Is the segfault really by-design? It might sound facetious, but that's the 90% of bugs: not specifically segfaults, but trivial mistakes, invalid values and logic problems. Only a debugger can show you the steps and conditions involved that lead to that invalid value. Sometimes, through debugging, you find a problem that does span multiple layers or components. If something spans multiple layers or components then that's a design problem. When you are solving a bug like this you have to "debug" at a much higher abstraction level. You shouldn't use a debugger for this (as you've pointed out); you should use a team of peers (documentation alone is not the correct tool). That team might rely on documentation, but would have to keep in mind that documentation rots over time. If you're solving the former with the processes of the latter, I'm surprised you get anything done. Documentation won't tell you where an invalid value originates from or why. Only extremely verbose logging or debugging can do that.
- wolfgke 8y ago
  > If a developer doesn't check for a null value, are you really going to head to the documentation to find out why? Yes. I often write code in a way such that no null is checked. But if I do so, I always document it properly and my reasoning why, if the function is used properly, no null will be passed. This way, you can be sure that if a null is dereferenced, not my function is the source of the bug, but a function that does not obey the pre-invariants that my function imposes on its parameters. So you know that you are not supposed to "fix" this bug by introducing a null check to my function, but instead fix the bug in the other function that calls mine.
  - dotancohen 8y ago
    I hope that you're leaving a comment in the function noting why you think that NUL should not be checked. Also, depending on the field, you might want to consider defensive programming.
    - wilun 8y ago
      The meaning of "defensive programming" is highly contextual even within a given "field". Also, major influential parts of the industry (last example in date being the C++ committee) are moving away from indistinct checks and exceptions, and toward contractual programming.
WiseWeasel 8y ago
For anything complex, you'll probably need a combination of both approaches (or some method of examining the existing codebase), and then go down another layer of whys. Why is the code written the way it is in the context of the business goals? Why is there this undocumented behavior? Why does the business requirement say x while the code does y?
munchbunny 8y ago
This worked for me when I was working with startup sized codebases doing mostly CRUD app stuff. Once you know how it's generally laid out you can start being productive. But now I'm working on nuts and bolts cybersecurity stuff for a tech giant. Stuff like public key infrastructure. Even if I know why things are done, stepping through someone else's code with expected behaviors, pathological cases, and error cases has been extremely helpful because there are so many more subtleties to worry about.
kovrik 8y ago
Agree. Yes, ability to explore and understand the project via debugger is a great and useful skill. However, if it takes debugger to understand that project, then, I'd say, it is a badly written and poorly documented project.

dalbasal 8y ago

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.

sorahn 8y ago

A lot of modern IDEs are debuggers too. So now you’re reading the code, in your document reader, but it’s got a bunch of the variables filled in with real values.

adamnemecek 8y ago

These are orthogonal. Yes, why's would be nice but you will never actually get a satisfying answer. Debuggers are I guess the best option.

pjc50 8y ago

This would be nice, but who wants to write the why? If you're lucky, you've got the commit messages and associated bug/work tracker items that explain where the software comes from. I agree there's no substitute for planning documents, but those don't always survive confrontation with the enemy.

zamalek 8y ago

> WHY If a developer doesn't check for a null value, are you really going to head to the documentation to find out why? Is the segfault really by-design? It might sound facetious, but that's the 90% of bugs: not specifically segfaults, but trivial mistakes, invalid values and logic problems. Only a debugger can show you the steps and conditions involved that lead to that invalid value. Sometimes, through debugging, you find a problem that does span multiple layers or components. If something spans multiple layers or components then that's a design problem. When you are solving a bug like this you have to "debug" at a much higher abstraction level. You shouldn't use a debugger for this (as you've pointed out); you should use a team of peers (documentation alone is not the correct tool). That team might rely on documentation, but would have to keep in mind that documentation rots over time. If you're solving the former with the processes of the latter, I'm surprised you get anything done. Documentation won't tell you where an invalid value originates from or why. Only extremely verbose logging or debugging can do that.

wolfgke 8y ago
> If a developer doesn't check for a null value, are you really going to head to the documentation to find out why? Yes. I often write code in a way such that no null is checked. But if I do so, I always document it properly and my reasoning why, if the function is used properly, no null will be passed. This way, you can be sure that if a null is dereferenced, not my function is the source of the bug, but a function that does not obey the pre-invariants that my function imposes on its parameters. So you know that you are not supposed to "fix" this bug by introducing a null check to my function, but instead fix the bug in the other function that calls mine.
- dotancohen 8y ago
  I hope that you're leaving a comment in the function noting why you think that NUL should not be checked. Also, depending on the field, you might want to consider defensive programming.
  - wilun 8y ago
    The meaning of "defensive programming" is highly contextual even within a given "field". Also, major influential parts of the industry (last example in date being the C++ committee) are moving away from indistinct checks and exceptions, and toward contractual programming.

WiseWeasel 8y ago

For anything complex, you'll probably need a combination of both approaches (or some method of examining the existing codebase), and then go down another layer of whys. Why is the code written the way it is in the context of the business goals? Why is there this undocumented behavior? Why does the business requirement say x while the code does y?

munchbunny 8y ago

This worked for me when I was working with startup sized codebases doing mostly CRUD app stuff. Once you know how it's generally laid out you can start being productive. But now I'm working on nuts and bolts cybersecurity stuff for a tech giant. Stuff like public key infrastructure. Even if I know why things are done, stepping through someone else's code with expected behaviors, pathological cases, and error cases has been extremely helpful because there are so many more subtleties to worry about.

kovrik 8y ago

Agree. Yes, ability to explore and understand the project via debugger is a great and useful skill. However, if it takes debugger to understand that project, then, I'd say, it is a badly written and poorly documented project.