Comment by aDyslecticCrow

I fundamentally disagree on code readability. A comment on the function header can save an hour of code reverse engineering for a complex library. Reading code is a last resort, and stale code docs is itself a red flag.

This post itself is a great example. The code is not self explanatory unless you understand the library below. So if this was library code; you would have to reverse through two abstraktion walls to understand it.

And as for high level documentation... it would be very helpful to have that DURING the development process to discuss the implementation, and quickly get people up-to-speed in the plan during code review. Id write that before the code.

I mention tests, because they are 10x more work to write than docs. So if the developer skips out on docs, my trust in their testing is also destroyed.