---
title: Philosophy
description: How we think about building Biome.
---

This list includes general ethos that the project should abide by.
This list is not comprehensive. Some of these are obvious but are stated for completeness.

## Project Management

- **Set clear expectations.** Make project intent and decisions known well in advance.
  Nothing should be a surprise.

- **Clear messaging of decisions.** The team might evaluate options and make decisions using private channels.
  Team will try to keep discussions using public channels like [GitHub discussions](https://github.com/biomejs/biome/discussions) or [Discord](https://biomejs.dev/chat). Frequent private check-ins might happen.
  When decisions occur via private channels, the team has to commit to communicate these decisions using the public channels.

## Technical

- **Errors should suggest fixes and hints where possible.** These should be inferred and filtered from usage to reduce surfacing irrelevant and unhelpful messages.

- **Unique and specific error messages.** No generic error messages.
  This helps users understand what went wrong and should provide maintainers with a unique call site and the necessary information to debug.

- **Optimise API.** Question the existence of all options and flags.
  Are they necessary? Can they be combined? How can we reduce code branching?

- **Document Code.** Strive to document the code as much as possible, especially the "hard-to-read" code, or for special logic that requires explanation.
  A well documented code helps its maintainability, especially when multiple people work on it. The developer after you will benefit from your knowledge, share it.

- **Reduce jargon.** Don't assume that users will understand specific terminology.
  Strive to provide precise meaning for experts and beginners.
  For example, use "character" where you would traditionally use "token" when producing parser errors.

- **Utilize verbosity when naming commands and flags.** No unnecessary and confusing abbreviations.

- **Use inclusive terminology.** Use gender-neutral pronouns. No ableist slurs.
  No usage of terms that could be considered insensitive.

- **Build for generic clients.** Don't assume that a terminal will only consume output using ANSI codes.
  Use abstractions that could be generalized for viewing in an IDE, browser, or other environments.

- **Terminal output should be unambiguous.** When designing terminal output, don't rely purely on formatting cues like color.
  Always use a combination of formatting, symbols, and spacing.
  If all ANSI codes are stripped, all the output should still be understood.