Because all that information is essential to understanding. All of it
Why?
Othewise somebody will come two years later and try to refactor something, breaking things that cannot possibly be covered by tests.
How?
Note: the reason why I ask is, if someone tells me, "if you don't do X, the building will be set on fire, oceans will spill out of their shores, the sky will fall, the world will explode", I'd really like to have a convincing explanation of "how?"
cannot deduce information that was not there in the first place
That information you keep referring to. How was it obtained in the first place if not for derivation? Derivation from requirements and intention of the design?
Not to mention that reading the code should require as little thinking as possible
Why? I'd rather my colleagues be thoughtful whenever they write / read code.
Easily. Remember my example about twisted mitigation procedure for a rare latency glitch? Without a comprehensive comment anyone would just delete such a code with disgust.
And yes, information is in the requirements, in physical properties of the hardware, etc. - and you distill it through a very expensive and long engineering process before it's ready for consumption.
Want to be "thoughful" instead of consuming a distilled information? Ok. Let me present you with petabytes of raw data from LHC, I'm pretty sure you'll just deduce all of the Standard Model from it.
Whoever deletes code without consideration isn't a very reasonable programmer.
In that case perhaps it makes sense to add a comment. It still doesn't explain why everything has to be commented. Not all code is like that, most code just encodes business rules. No programmer that wants to keep their job would delete the code without thinking about the impact on business rules.
Let me present you with petabytes of raw data from LHC, I'm pretty sure you'll just deduce all of the Standard Model from it.
It's funny that you say that. You're the person who says they need all the information all the time when you code.
If someone needs to encode some physics and mathematics theory, there's obviously a need for either comments or another document with derivations, or just a name of the theory, a law, etc. This stuff would be helpful. It doesn't mean that everything has to be commented and only a small portion of the time should be spent on code.
Not all code is like that, most code just encodes business rules.
You don't even need code to encode business rules. Write them down as is.
As I said, all this "clean code" religion is only viable for a low effort mindless CRUD-level boilerplate code. Anything marginally more complex, anything that actually worth writing (instead of just automating all the boilerplate), must be commented heavily.
If you find yourself writing all that "business rules" code that does not even need to be commented, you're doing it wrong, it's just a massively inefficient busywork that can be fully automated.
And what should absolutely be documented in tiniest detail, ideally in place, along with the code itself, is where did you get those business rules from.
It's always so funny to find out that nobody have any idea of an origin of some rule that was in the code since forever and was faithfully copied into many systems.
You're the person who says they need all the information all the time when you code.
Information, not data. By definition, data is information + noise.
Again, your response didn't address any of my points. For example, where do you get the idea that clean code only applies to CRUD-level complexity? Why do you need all information all the time, as a comment?
You also don't seem to have an understanding of what business rules are, hence seem to think they can be automated. Business rules are basically any feature or an edge case that your product satisfies. In other words, business rules are requirements for the software product. They take form when a programmer implements them as code.
massively inefficient busywork that can be fully automated
If that was true, programmers would cease to exist. Because any manager would just wave a magic wand, say "I want my product to do X", and it would instantly be implemented.
And what should absolutely be documented in tiniest detail, ideally in place, along with the code itself, is where did you get those business rules from.
I think actually the best way is to link Jira with your commits. Jira will describe the requirements and maybe even research, contain links to further documentation, and you can always find a reference to the Jira ticket from every commit you make. You can always find the information with a few clicks, and it's not distracting you every time you look at the code.
For example, where do you get the idea that clean code only applies to CRUD-level complexity?
From an obvious fact that anything more complex than that is meaningless without tons of background information.
Another example: say, you're implementing some standard. Naming things (modules, functions, classes, whatever) as paragraph numbers of a standard would not make much sense, you'd rather want semantic names, not to mention that one piece of code may address few different paragraphs.
A right thing to do is to refer to those paragraphs in comments. Even better - just copy and paste them, as they're very relevant to your implementation and would save a reader a click and few searches for every little piece of code they're trying to understand. Additionally, it's now versioned with your code. I had a number of unfortunate incidents related to reading a wrong standard edition while looking at a code implementing it.
Now, this standard mentions undefined behaviour quite a bit. You can just implement it in code any way you like, but it's much better to justify your choice of implementation-specific or undefined behaviour, make sure it's consistent for similar cases, etc.
If it's well documented, right where it's actually implemented in code, you're more likely to have consistency and to be able to easily find what this behaviour is in specific cases.
You also don't seem to have an understanding of what business rules are, hence seem to think they can be automated.
Please read more carefully. Encoding them must be automated, not the rules themselves. Rules are given, and all you can do is understand and document where they came from. But your ways of programming (all that OOPish SOLID "clean code" mumbo-jumbo) is designed to obscure the rules behind tons and tons of boilerplate code, the code that should not even exist in the first place.
If that was true, programmers would cease to exist.
In an ideal world, no programmers should waste their time encoding business rules. Luckily, there's a lot of much more exciting things to do instead.
Unfortunately, this world is far from ideal, and a vast majority of programmers and managers prefer busywork to any degree of efficiency. Most of the code written is a worthless pile of crap, and everyone involved seems to be ok with this fact.
I think actually the best way is to link Jira with your commits.
No, no, no, please don't do it! It's the worst possible idea, ever. I hate to deal with such code.
Your code is nicely versioned. Jira is not. Just like any other external source - Confluence, whatever else. Then you have to come back to a 5 years old branch to fix an issue for a customer still using this old release, and all you see is a pile of stale links and zero context. Unless you can version your Jira and Confluence along with your code, you should not use them for anything relevant to understanding the code.
Some comments have been hidden by the post's author - find out more
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Why?
How?
Note: the reason why I ask is, if someone tells me, "if you don't do X, the building will be set on fire, oceans will spill out of their shores, the sky will fall, the world will explode", I'd really like to have a convincing explanation of "how?"
That information you keep referring to. How was it obtained in the first place if not for derivation? Derivation from requirements and intention of the design?
Why? I'd rather my colleagues be thoughtful whenever they write / read code.
Easily. Remember my example about twisted mitigation procedure for a rare latency glitch? Without a comprehensive comment anyone would just delete such a code with disgust.
And yes, information is in the requirements, in physical properties of the hardware, etc. - and you distill it through a very expensive and long engineering process before it's ready for consumption.
Want to be "thoughful" instead of consuming a distilled information? Ok. Let me present you with petabytes of raw data from LHC, I'm pretty sure you'll just deduce all of the Standard Model from it.
Whoever deletes code without consideration isn't a very reasonable programmer.
In that case perhaps it makes sense to add a comment. It still doesn't explain why everything has to be commented. Not all code is like that, most code just encodes business rules. No programmer that wants to keep their job would delete the code without thinking about the impact on business rules.
It's funny that you say that. You're the person who says they need all the information all the time when you code.
If someone needs to encode some physics and mathematics theory, there's obviously a need for either comments or another document with derivations, or just a name of the theory, a law, etc. This stuff would be helpful. It doesn't mean that everything has to be commented and only a small portion of the time should be spent on code.
You don't even need code to encode business rules. Write them down as is.
As I said, all this "clean code" religion is only viable for a low effort mindless CRUD-level boilerplate code. Anything marginally more complex, anything that actually worth writing (instead of just automating all the boilerplate), must be commented heavily.
If you find yourself writing all that "business rules" code that does not even need to be commented, you're doing it wrong, it's just a massively inefficient busywork that can be fully automated.
And what should absolutely be documented in tiniest detail, ideally in place, along with the code itself, is where did you get those business rules from.
It's always so funny to find out that nobody have any idea of an origin of some rule that was in the code since forever and was faithfully copied into many systems.
Information, not data. By definition, data is information + noise.
Again, your response didn't address any of my points. For example, where do you get the idea that clean code only applies to CRUD-level complexity? Why do you need all information all the time, as a comment?
You also don't seem to have an understanding of what business rules are, hence seem to think they can be automated. Business rules are basically any feature or an edge case that your product satisfies. In other words, business rules are requirements for the software product. They take form when a programmer implements them as code.
If that was true, programmers would cease to exist. Because any manager would just wave a magic wand, say "I want my product to do X", and it would instantly be implemented.
I think actually the best way is to link Jira with your commits. Jira will describe the requirements and maybe even research, contain links to further documentation, and you can always find a reference to the Jira ticket from every commit you make. You can always find the information with a few clicks, and it's not distracting you every time you look at the code.
From an obvious fact that anything more complex than that is meaningless without tons of background information.
Another example: say, you're implementing some standard. Naming things (modules, functions, classes, whatever) as paragraph numbers of a standard would not make much sense, you'd rather want semantic names, not to mention that one piece of code may address few different paragraphs.
A right thing to do is to refer to those paragraphs in comments. Even better - just copy and paste them, as they're very relevant to your implementation and would save a reader a click and few searches for every little piece of code they're trying to understand. Additionally, it's now versioned with your code. I had a number of unfortunate incidents related to reading a wrong standard edition while looking at a code implementing it.
Now, this standard mentions undefined behaviour quite a bit. You can just implement it in code any way you like, but it's much better to justify your choice of implementation-specific or undefined behaviour, make sure it's consistent for similar cases, etc.
If it's well documented, right where it's actually implemented in code, you're more likely to have consistency and to be able to easily find what this behaviour is in specific cases.
Please read more carefully. Encoding them must be automated, not the rules themselves. Rules are given, and all you can do is understand and document where they came from. But your ways of programming (all that OOPish SOLID "clean code" mumbo-jumbo) is designed to obscure the rules behind tons and tons of boilerplate code, the code that should not even exist in the first place.
In an ideal world, no programmers should waste their time encoding business rules. Luckily, there's a lot of much more exciting things to do instead.
Unfortunately, this world is far from ideal, and a vast majority of programmers and managers prefer busywork to any degree of efficiency. Most of the code written is a worthless pile of crap, and everyone involved seems to be ok with this fact.
No, no, no, please don't do it! It's the worst possible idea, ever. I hate to deal with such code.
Your code is nicely versioned. Jira is not. Just like any other external source - Confluence, whatever else. Then you have to come back to a 5 years old branch to fix an issue for a customer still using this old release, and all you see is a pile of stale links and zero context. Unless you can version your Jira and Confluence along with your code, you should not use them for anything relevant to understanding the code.