diff --git a/AGENTS.md b/AGENTS.md index 3df71f641..eeec0c341 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,8 +5,9 @@ ## Style Guide +### General Principles + - Keep things in one function unless composable or reusable -- Avoid unnecessary destructuring. Instead of `const { a, b } = obj`, use `obj.a` and `obj.b` to preserve context - Avoid `try`/`catch` where possible - Avoid using the `any` type - Prefer single word variable names where possible @@ -14,70 +15,97 @@ - Rely on type inference when possible; avoid explicit type annotations or interfaces unless necessary for exports or clarity - Prefer functional array methods (flatMap, filter, map) over for loops; use type guards on filter to maintain type inference downstream -### Avoid let statements +### Naming -We don't like `let` statements, especially combined with if/else statements. -Prefer `const`. - -Good: +Prefer single word names for variables and functions. Only use multiple words if necessary. ```ts -const foo = condition ? 1 : 2 +// Good +const foo = 1 +function journal(dir: string) {} + +// Bad +const fooBar = 1 +function prepareJournal(dir: string) {} ``` -Bad: +Reduce total variable count by inlining when a value is only used once. ```ts -let foo +// Good +const journal = await Bun.file(path.join(dir, "journal.json")).json() +// Bad +const journalPath = path.join(dir, "journal.json") +const journal = await Bun.file(journalPath).json() +``` + +### Destructuring + +Avoid unnecessary destructuring. Use dot notation to preserve context. + +```ts +// Good +obj.a +obj.b + +// Bad +const { a, b } = obj +``` + +### Variables + +Prefer `const` over `let`. Use ternaries or early returns instead of reassignment. + +```ts +// Good +const foo = condition ? 1 : 2 + +// Bad +let foo if (condition) foo = 1 else foo = 2 ``` -### Avoid else statements +### Control Flow -Prefer early returns or using an `iife` to avoid else statements. - -Good: +Avoid `else` statements. Prefer early returns. ```ts +// Good function foo() { if (condition) return 1 return 2 } -``` -Bad: - -```ts +// Bad function foo() { if (condition) return 1 else return 2 } ``` -### Prefer single word naming +### Schema Definitions (Drizzle) -Try your best to find a single word name for your variables, functions, etc. -Only use multiple words if you cannot. - -Good: +Use snake_case for field names so column names don't need to be redefined as strings. ```ts -const foo = 1 -const bar = 2 -const baz = 3 -``` +// Good +const table = sqliteTable("session", { + id: text().primaryKey(), + project_id: text().notNull(), + created_at: integer().notNull(), +}) -Bad: - -```ts -const fooBar = 1 -const barBaz = 2 -const bazFoo = 3 +// Bad +const table = sqliteTable("session", { + id: text("id").primaryKey(), + projectID: text("project_id").notNull(), + createdAt: integer("created_at").notNull(), +}) ``` ## Testing -You MUST avoid using `mocks` as much as possible. -Tests MUST test actual implementation, do not duplicate logic into a test. +- Avoid mocks as much as possible +- Test actual implementation, do not duplicate logic into tests