Title: Coding principles
Published: July 15, 2026
Last modified: July 16, 2026

---

# Coding principles

## In this article

 * [Error messages](https://developer.wordpress.org/playground/handbook/contributing/coding-standards/?output_format=md#error-messages)
 * [Public API](https://developer.wordpress.org/playground/handbook/contributing/coding-standards/?output_format=md#public-api)
 * [Blueprints](https://developer.wordpress.org/playground/handbook/contributing/coding-standards/?output_format=md#blueprints)
    - [Guidelines](https://developer.wordpress.org/playground/handbook/contributing/coding-standards/?output_format=md#guidelines)

[ Back to top](https://developer.wordpress.org/playground/handbook/contributing/coding-standards/?output_format=md#wp--skip-link--target)

## 󠀁[Error messages](https://developer.wordpress.org/playground/handbook/contributing/coding-standards/?output_format=md#error-messages)󠁿

A good error message informs the user of the following steps to take. Any ambiguity
in errors thrown by Playground [Public APIs](https://developer.wordpress.org/playground/developers/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](https://developer.wordpress.org/playground/handbook/contributing/coding-standards/?output_format=md#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 functions, classes, constants, or other components.

## 󠀁[Blueprints](https://developer.wordpress.org/playground/handbook/contributing/coding-standards/?output_format=md#blueprints)󠁿

[Blueprints](https://developer.wordpress.org/playground/blueprints/getting-started)
are the primary way to interact with Playground. These JSON files describe a set
of steps that Playground executes in order.

### 󠀁[Guidelines](https://developer.wordpress.org/playground/handbook/contributing/coding-standards/?output_format=md#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.

First published

July 15, 2026

Last updated

July 16, 2026

Edit article

[ Improve it on GitHub: Coding principles ](https://raw.githubusercontent.com/WordPress/wordpress-playground/trunk/packages/docs/site/docs/main/contributing/coding-standards.md)

Changelog

[ See list of changes: Coding principles ](https://developer.wordpress.org/playground/handbook/contributing/coding-standards/?output_format=md#)

[  Previous: Releasing packages](https://developer.wordpress.org/playground/handbook/contributing/releases/)

[  Next: WordCamp Contributor Day](https://developer.wordpress.org/playground/handbook/contributing/contributor-day/)