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.

Sign up for GitHub

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

Jump to bottom

First pass at #453 (text-based syntaxes should be designed for humans) #472

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

First pass at #453 (text-based syntaxes should be designed for humans) #472

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -841,6 +841,31 @@ that authors can use to extend the language
without breaking future native functionality,
to reduce such dilemmas in the future.

<h3 id="text-based-syntaxes">Design text-based syntax with humans in mind</h3>

When designing a text-based syntax, consider human usability and readability,
even when you expect the syntax to be primarily generated by tooling.

Historically, every syntax that could be read by humans, inevitably ended up being authored by humans too.
Even when syntax is primarily authored by tools,
it is still effectively authored by humans: the tool developers.
Therefore, optimizing it for human usability also makes it easier to develop tools to generate it.

Human usability may often be at odds with parsing performance and filesize efficiency.
Ideally, the syntax would be optimized for human usability, and tooling would optimize the syntax for efficiency.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was a little unclear as to what this line was trying to say; @LeaVerou explained it's about situations e.g. where you can minify a file with tooling to make it more efficient - that was good clarification I think, so I suggest including that in the text.

It feels like there could be quite big implications here (accepting tooling as integral to the process, if we've not already explicitly done so elsewhere). Solving for both human readability and efficiency is an important challenge.

However, this is not always possible.
In these cases, explore if it is possible to provide syntax that is flexible enough to accommodate both use cases.
The downside of this approach is that it increases the complexity of the language, and humans may still need to read the less human-friendly syntax.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what this sentence is getting at. What less-friendly syntax are you talking about?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's talking about cases where you need two have two syntaxes, one optimized for efficiency and one for humans.

Lastly, if efficiency is truly critical, consider whether a binary format may be more appropriate.

<div class="example">
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@plinss and @LeaVerou also gave JSON as a great example (+1 to both of these from me):

  • Not allowing trailing commas is not good for humans.
  • Not allowing comments is really not good for humans.

SVG path syntax was designed to be terse and efficient,
as it was assumed it would primarily be generated by tooling.
While this assumption was correct for many use cases,
humans *do* hand author SVG paths for a variety of reasons,
and the experience can be quite painful.
</div>

<h2 id="html">HTML</h2>

This section details design principles for features which are exposed via HTML.
Expand Down