Repository navigation
Normalize descriptions of syntax #905
Description
We have inconsistent uses of terminology for describing syntax. I've seen at least three:
- X is written as...
- X consists of...
- X is denoted with...
We should pick a single style, and use it consistently.
It doesn't have to be one of the above forms. I feel like we could be more explicit with the form:
- The syntax of X is...
For example, using the type cast expression:
The syntax of a type cast expression is an operand, the keyword
as, and finally a type.
cc @ehuss for opinions.
Activity
ehuss commentedon Nov 25, 2020
I'm not a big fan of writing the syntax in English, since it just reiterates what is shown in the grammar in a more wordy and less-presice way. Most other specs seem to just rely on the grammar without spelling it out (although some specs are also inconsistent, for example C# spells out the switch statement, but doesn't do that anywhere else).
My preference would be to just remove those sentences altogether. If it is written out, I think your last suggestion looks better than all the others.
Havvy commentedon Nov 29, 2020
One of the advantages of keeping it in the prose is that we can give names to specific syntactic elements which we can then refer to later in the documentation.
There's also the advantage that you don't have to understand the grammar language if you don't already know it. So, in that sense, it's more accessible to newer programmers.