Documentation

> Comments however are the last resort, because we're writing code which inherently _has_ meaning.

No, it does not.

> We should try to capture as much as possible of our meaning in that code, where a maintenance programmer is obliged to change it if they change the intended meaning later, whereas the comments can become out-of-sync with the code either through oversight or misunderstanding.

Yes, they can. However, they are hard to ignore if without a comment one is unable to understand the code.

> Modern optimising compilers can assist greatly here by allowing us to more often express what we actually meant,

They are useless.

> this is one of the opportunities for Rust once that's an option.

It is completely useless.

> C doesn't even have iterators, you can't express "are all the doodads in this bag of doodads sparkly?" except by explicitly enumerating them

Iterators don't help.

Let me explain what kinds of detailed comments are useful (picked at random from a codebase):

- «Calling this external API simultaneously using the same API key causes it to lock up, so there is a mutex»
- «Detaching a disk from a VM before Linux has booted causes a desynchronization of disk names inside the VM and in the libvirt, so wait for an r/w activity on the disk as a telltale of mounted root filesystem before detaching it»
- «This certificate is used in a closed-loop system, so CA/B requirements do not apply to it»
- «Here's the reverse-engineered description of undocumented IPC»
- «mount(2) contains a lot of historical baggage, and that baggage, unfortunately, got leaked to the external system interface, so the following code mimics the mount(8)»

These are facts about other systems.