And someone will then have to puzzle through what they assume is "well-written code" to work out what broke when things failed... I tend to comment rather heav

And someone will then have to puzzle through what they assume is "well-written code" to work out what broke when things failed... I tend to comment rather heavily, in the "free form" style frowned on here. However, most of my code is directly related to hardware, in some form or another, and "Assuming the person reading the code has the full hardware reference manual memorized" is simply a jerk move. There are plenty of things like direct accesses to particular memory addresses that, even with plenty of #define wrappers, are still a bit obscure unless you know what, exactly, that bit is doing. And that's before you get into weird corner cases of hardware or doing things outside the norm where even if the code is clear, it's only because you already know what it's trying to do. It's an interesting goal and may work in a few small corners of the software industry, but having spent plenty of time sorting through what assumptions about the state of things "well written code" (which is usually a lie anyway... what's obvious to one person may not be obvious to a different person with a different background and different expectations about the code), I'll take something with a couple hundred lines of explanation at the top of the file covering the concepts the file intends to implement over bare code, any day.