Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Normalize descriptions of syntax #905

Open
Havvy opened this issue Nov 20, 2020 · 2 comments
Open

Normalize descriptions of syntax #905

Havvy opened this issue Nov 20, 2020 · 2 comments
Labels
Formatting Style and markup

Comments

@Havvy
Copy link
Contributor

Havvy commented Nov 20, 2020

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.

@Havvy Havvy added the Formatting Style and markup label Nov 20, 2020
@ehuss
Copy link
Contributor

ehuss commented 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
Copy link
Contributor Author

Havvy commented 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Formatting Style and markup
Projects
None yet
Development

No branches or pull requests

2 participants