Philosophy

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

Section titled 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 or Discord. 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

Section titled 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.