Make spec more declarative

[dankrad]

On a long flight without Wifi, I finally had the time to read the whole current beacon chain document. I noticed that to mentally decode many parts of the spec, I had to cross-reference many different sections, because the meaning of objects is often not clear from their definition.

What I am suggesting is that each object/data type/etc. should contain a declarative description of its content. As an example

'justification_bitfield': 'uint64'

currently has no human-readable description. I have to read the code to understand what it does. The code might have edge cases and I have to figure out whether these are handled as intended, or might constitute bugs. I would suggest to add a comment like this:

# justification_bitfield: Bitfield that records justification for the last 64 epochs
# (justification_bitfield << i) & 0b1 == 1iff current_epoch - i is justified
'justification_bitfield': 'uint64',

If we do this, we get a couple of advantages:

• Reading the spec becomes much more straightforward -- if the field is referenced somewhere and I need to know what it does, I can probably just read the description and don't need to cross-reference the code where it's calculated
• We get access to the "mental model" of the objects without having to parse code
• If I find a discrepancy between the declarative description and the code that computes it, I know that there is a bug. Currently I have to search for the other code that uses it to confirm whether my "mental model" of some descriptor is right or not

[dankrad]

BTW, I disagree with the label "presentation" here. I believe if there is a description and it conflicts with the code, then the human-readable description should win. Yes, I know, I am old-fashioned on this one ;)

[vbuterin]

I agree that what's "reasonable" in an intuitive human sense should win over formalized code/specs. I think the purpose of the "presentation" label is that you're not proposing substantive changes to the spec, but rather changes to how the spec is presented. Tagging changes this way is good because client devs know that they don't have to worry about keeping up with it, because if their old way of implementing things is correct it will stay correct.

[dankrad]

OK, I would agree if this is how "presentation" should is defined. Would still be interested if people agree that more human readable definitions should be added to the spec, if so I would be making a first attempt for the containers to see where it leads. Of course, this leads to more lines at the same level of complexity :)

[JustinDrake]

@dankrad I have addressed this in #1156 (see 7cd7659 specifically). Please comment there :)