Document decisions taken

[JackKelly]

Ideas from Jon Gjenset's talk "Towards Impeccable Rust" at Rust Nation UK 2024 on Wednesday 27th March 2024:

Why does it work like this? In particular:

• What alternatives were discarded and why?
• What downsides were explicitly accepted and why?

No perfect method to document these decisions. Try (Y)ADRs? Make sure there's something.

Why is it important to document this stuff?

• To minimise the amount of information that's only in the lead developer's head. To reduce the "bus factor".
• So new developers (or you a few months down the line) don't re-do work by thinking "oh, this should work differently... let me try x... oh, wait, x isn't viable..."

Document what's not there. What shortcuts did we take? Document missing handling of corner-cases. Ideally use todo!() or unimplemented!() so these code paths fail. But also document what is missing and why!

Document future optimisations.

Document why some impl are missing (e.g. because it would lead to UB). impl From is particularly important to document.

Jack: At the very least, I should get better and concluding GitHub issues with a decision, and maybe summarise the options considered.

Related

• Rigorous automated testing #118
• Rigorous benchmarking #119