[KronisLV]

> The code should explain what it's doing (self documenting code) and tests should explain why it's doing it.

I agree at a surface level, however:

  - this makes us assume that there are tests in the first place
  - this makes us assume that someone will read these tests instead of asking the developer
  - this makes us assume that these tests will be readable enough on their own to replace free form text
  - this makes us assume that these tests will even be able to contain a representation of why the code exists
  - personally, i have never seen a test that explains a business requirement with enough context not to miss out on details
  - i have also never seen code that encapsulates these requirements 1:1, without getting too mixed up in implementation details

I think that code definitely should describe what it's doing, tests should explain how it's doing it as far as possible (though this requires discipline to have loosely coupled and testable code, which isn't always the case) and that there still should be comments that explain the realities of needing technical solutions for people problems and all of the aspects that are carried with this.

Doing anything less feels like giving ourselves constraints that will lead to suboptimal results because the tooling and testing solutions aren't quite there yet. Maybe when frameworks and languages will become more expressive, we'll be able to live without comments. However, that day may not come anytime soon.

Nor will companies be interested in the overhead that writing extensive and good tests entail, nor will they want to wait for their engineers to figure out how to convey everything in computer code, as opposed to just dropping some comments into the codebase, right next to the actual code that they concern. Maybe when companies are ready for 50% of the development time to be spent on testing software, that won't be an issue. That day may also not come anytime soon.

As a possible counterpoint, look at RSpec, i think it's headed in the right direction: https://rspec.info/