Thoughts on this approach. I think adding such narratives could be helpful to some readers, though it adds a risk of conflict between the narrative and the code. As an alternate we could better define how to read the code. I don't want to presume too much that it is intuitive.

Going to drop this PR in favor of offering some context in the document to explain that C-like code-blocks are used to explain the storage of the components of FFV1.

+1
Yet why «C-like»? Is it not possible to use plain C code-fragments?

Yet why «C-like»? Is it not possible to use plain C code-fragments?

plain C is more verbose and more difficult to read, and permits lot of traps.
Additionally, plain C adds more constraints (e.g. is the integer type 8-bit or 16-bit? how do you handle integer overflows? it should depend of your design choice,) the spec should be neutral (e.g. consider number as unlimited, as integer overflow methods are specific to each language or CPU or something else)

I understand your arguments, but I don’t agree with you, except the increased verbosity.

BTW: In my teaching experience, Pascal-style pseudo code is often considered more intuitive than C-style pseudo code by the students.