Skip to main content

Coding principles

Error messages

A good error message tells the user what to do next. Any ambiguity in errors thrown by Playground public APIs will prompt the developers to open issues.

Consider a network error, for example—can we infer the type of error and display a relevant message summarizing the next steps?

  • Network error: "Your internet connection twitched. Try to reload the page.
  • 404: "Could not find the file".
  • 403: "The server blocked access to the file".
  • CORS: clarify it's a browser security feature and add a link to a detailed explanation (on MDN or another reliable source). Suggest the user move their file somewhere else, like raw.githubusercontent.com, and link to a resource explaining how to set up CORS headers on their servers.

We handle code formatting and linting automatically. Relax, type away, and let the machines do the work.

Public API

Playground aims to keep the narrowest possible API scope.

Public APIs are easy to add and hard to remove. It only takes one PR to introduce a new API, but it may take a thousand to remove it, especially if other projects have already consumed it.

  • Don't expose unnecessary function, class, constant, or other components.

Blueprints

Blueprints are the primary way to interact with Playground. These JSON files describe a set of steps that Playground executes in order.

Guidelines

Blueprint steps should be concise and focused. They should do one thing and do it well.

  • If you need to create a new step, try refactoring an existing one first.
  • If that's not enough, ensure the new step delivers a new capability. Don't replicate the functionality of existing steps.
  • Assume the step would be called more than once.
  • Assume it would run in a specific order.
  • Add unit tests to verify that.

Blueprints should be intuitive and straightforward.

  • Don't require arguments that can be optional.
  • Use plain argument. For example, slug instead of path.
  • Define constants in virtual JSON files—don't modify PHP files.
  • Define a TypeScript type for the Blueprint. That's how Playground generates its JSON schema.
  • Write a function to handle a Blueprint step. Accept the argument of the type you defined.
  • Provide a usage example in the doc string. It's automatically reflected in the docs.