Eeviriyi Style Guide

Introduction

Welcome to the Eeviriyi Style Guide! This document provides a comprehensive set of guidelines and best practices for writing consistent, readable, and maintainable code within our projects. By adhering to these standards, we aim to foster collaboration, reduce cognitive load, and improve the overall quality and longevity of our codebase.

This guide is specifically tailored for projects utilizing Deno, leveraging Biome for formatting and linting, incorporating Tailwind CSS for utility-first styling, and assuming VS Code as the primary development environment.

General Principles

Before diving into specifics, let's establish some overarching principles:

  • Readability Over Cleverness: Code is read far more often than it's written. Prioritize clarity and simplicity.
  • Consistency is Key: A consistent codebase is easier to navigate, understand, and maintain, even if a particular convention isn't universally "perfect."
  • Embrace Tooling: Leverage tools like Biome and VS Code's features to automate style enforcement, allowing developers to focus on logic rather than formatting.
  • Pragmatism: While this guide provides strong recommendations, there might be rare justified exceptions. Discuss significant deviations with your team.

Deno & TypeScript Conventions

File Naming

  • Use kebab-case for file names (e.g., my-component.ts, utility-functions.ts).
  • For modules exporting a single default item, the file name should match the export (e.g., UserCard.ts exporting class UserCard).
  • Test files should end with .test.ts or .spec.ts (e.g., user-service.test.ts).

Imports & Exports

  • Explicit Imports: Always use explicit file extensions in Deno imports.
  • Ordered Imports: Group imports by type: Deno standard library, third-party modules, then local modules. Use an empty line to separate groups.
  • Absolute vs. Relative: Prefer relative paths for modules within the same project feature. Use absolute paths (or Deno's import_map.json if configured) for global utilities or common components.
  • Barrel Files (Index Modules): Use mod.ts or index.ts within directories to export multiple modules, simplifying imports from other parts of the application.

Imports & Exports

  • Be Explicit: Strongly type your functions, variables, and parameters. Leverage TypeScript's inference where it's clear, but prefer explicit types for public APIs and complex logic.
  • Interfaces vs. Types: Generally prefer type for aliases and unions/intersections, and interface for declaring object shapes. Both are largely interchangeable for object types.
  • Enums: Prefer TypeScript const enum for simple, compile-time constant enums or union types for more flexible string/number literal enums.