4 ms·

What if the teams changes? Intricacies must be documented despite that probably nobody will ever read it. Somebody might depend on it. Writing code is more abo

What if the teams changes? Intricacies must be documented despite that probably nobody will ever read it. Somebody might depend on it. Writing code is more about communicating how to solve a problem than just solving a problem, that's how I view it. If you don't communicate, nobody except you will ever understand it. It might be that you don't need to document a lot, maybe most is obvious if the key parts are sufficiently explained. But it's vital and sometimes it's better to write a bit more than a bit less. A thing is, outdated documentation might be worse than none, so it's a delicate balance.

wruza 4y ago
What if the teams changes? Yeah, documentation will definitely help in this case. With it, you can swap teams and even companies, and it still works! This only fails in companies which do not review documentation and have no routine for keeping it in sync and testing it on e.g. newcomers, like you do for backups. Cause otherwise it is as good as never tested six months old backup.
- LeanderK 4y ago
  It's always fun if a product is based on 20 year old code where there are parts that nobody can touch because there's nobody around who understands what's going on there. I once saw a flight-training software (I think it was for helicopters?) where the physics engine just didn't get touched because they don't know what's going on. Every change was essentially a hack around this blob of years old, highly optimised but totally incomprehensible C. EDIT: It might have even been fortran code. The rest of the project was C++
  - onion2k 4y ago
    I once saw a flight-training software (I think it was for helicopters?) where the physics engine just didn't get touched because they don't know what's going on. This is an interesting case, because it's something that I probably wouldn't document. Code should be readable. If you're writing down how your code works in a document then something is wrong with the code. Documentation can't fix an incomprehensible codebase. I document how algorithms work, what the business logic is for things (which is another algorithm really), how applications work in a 'data flow' sense, what integrations there are with external services and how they work, what things mean, and so on.
    - native_samples 4y ago
      Normally working out how a complex piece of software works from only the source code is called reverse engineering. I've encountered this "readable code means I don't have to document" idea before. I have no time for it, it's just wrong: 1. Important things aren't easily visible in the code, most commonly why the code does a particular thing. "Readable" code, which is a very subjective standard, can only tell you what it does but not the underlying rationale. 2. Writing docs often exposes the fact that the way the code works, or is expected to be used, doesn't make sense or is sub-optimal. If your docs include lots of caveats or explanations of nonsensical behaviour then it's a good hint you should go back and think again. 3. Figuring out stuff by reading the code is often drastically slower than reading the docs. That's why all professional APIs have good docs and people grumble and moan when expected to use code that doesn't. 4. The sort of people who argue this, in my experience, often don't actually write readable code, they just tell themselves they do.

wruza 4y ago

What if the teams changes? Yeah, documentation will definitely help in this case. With it, you can swap teams and even companies, and it still works! This only fails in companies which do not review documentation and have no routine for keeping it in sync and testing it on e.g. newcomers, like you do for backups. Cause otherwise it is as good as never tested six months old backup.

LeanderK 4y ago
It's always fun if a product is based on 20 year old code where there are parts that nobody can touch because there's nobody around who understands what's going on there. I once saw a flight-training software (I think it was for helicopters?) where the physics engine just didn't get touched because they don't know what's going on. Every change was essentially a hack around this blob of years old, highly optimised but totally incomprehensible C. EDIT: It might have even been fortran code. The rest of the project was C++
- onion2k 4y ago
  I once saw a flight-training software (I think it was for helicopters?) where the physics engine just didn't get touched because they don't know what's going on. This is an interesting case, because it's something that I probably wouldn't document. Code should be readable. If you're writing down how your code works in a document then something is wrong with the code. Documentation can't fix an incomprehensible codebase. I document how algorithms work, what the business logic is for things (which is another algorithm really), how applications work in a 'data flow' sense, what integrations there are with external services and how they work, what things mean, and so on.
  - native_samples 4y ago
    Normally working out how a complex piece of software works from only the source code is called reverse engineering. I've encountered this "readable code means I don't have to document" idea before. I have no time for it, it's just wrong: 1. Important things aren't easily visible in the code, most commonly why the code does a particular thing. "Readable" code, which is a very subjective standard, can only tell you what it does but not the underlying rationale. 2. Writing docs often exposes the fact that the way the code works, or is expected to be used, doesn't make sense or is sub-optimal. If your docs include lots of caveats or explanations of nonsensical behaviour then it's a good hint you should go back and think again. 3. Figuring out stuff by reading the code is often drastically slower than reading the docs. That's why all professional APIs have good docs and people grumble and moan when expected to use code that doesn't. 4. The sort of people who argue this, in my experience, often don't actually write readable code, they just tell themselves they do.