Coding Style Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The Svelte Effect Runtime (SER) project follows a strict set of coding conventions designed to ensure clarity, maintainability, and consistency across its various modules, including the runtime, compiler, and language server. These guidelines cover naming conventions, code structure, documentation standards, and Git etiquette.
The primary focus of these guidelines is to support the development of effectful Svelte code while maintaining high code quality. Developers are expected to prioritize focused root-cause fixes over compatibility shims and to update runtime, compiler, and editor tooling in tandem when adding new syntax.
Sources: AGENTS.md:1-11, CONTRIBUTING.md:1-10, CONTRIBUTING.md:73-77
Naming Conventions
The project utilizes specific casing for different types of identifiers to maintain a clear visual distinction between logic, data structures, and files.
| Identifier Type | Convention | Example |
|---|---|---|
| Functions, variables, methods | snake_case | transform_script_effect, has_effect_import |
| Classes, types, interfaces, components | PascalCase | ScriptTransformResult, SourceRange |
| File names | kebab-case.ts | virtual-document.ts, source-scan.ts |
| Directories | Group by category | internal/transform.ts |
Sources: AGENTS.md:5-9, CONTRIBUTING.md:58-61
Code Structure and Spacing
Logic within functions is organized to "breathe," avoiding dense blocks of code. This is achieved through specific grouping and the use of blank lines to separate logical phases.
Phase-Based Organization
Functions are typically structured into distinct phases (e.g., Phase 1: Detect imports, Phase 2: Lower statements). Each phase is separated by a blank line and a /** */ doc comment summarizing the logic.
Spacing Rules
- Variables: Grouped at the top of the function.
- Guard Clauses: Used early and concisely to keep the "happy path" cleanly indented.
- Branches: If
if/elsebranches contain more than a single return, they must be separated by a blank line. - Returns: A blank line must precede a
returnstatement unless it follows a single guard clause.
Sources: AGENTS.md:27-40, AGENTS.md:42-83
Syntax Preferences
The project favors declarative, modern TypeScript operators over imperative loops and manual checks to express intent clearly.
| Preferred | Avoid |
|---|---|
x ?? default | if (x === null) x = default |
.some(predicate) | manual for loop with boolean flag |
.find(predicate) | manual for loop with break |
?. | Nested if (x && x.y) |
[...arr, item] | arr.push(item) for new arrays |
Sources: AGENTS.md:87-98
Documentation (JSDoc)
Documentation is mandatory for every exported function, class, and type. The project strictly forbids the use of bare // comments, requiring /** */ JSDoc style for all comments.
Required JSDoc Fields
- Brief Description: A one-line summary.
- @example: Realistic usage snippets.
- @since: Version tracking.
- @param: Detailed sentence for every parameter.
- @returns: Detailed description of the return value.
/**
* Finds best-effort SER usage diagnostics in Svelte component markup.
*
* @example
* ```ts
* const diagnostics = find_svelte_effect_diagnostics(code, "App.svelte");
* ```
*
* @since 2.0.0
* @param code - Svelte component source to scan.
* @param filename - Filename used in diagnostic messages.
* @returns Warning diagnostics with a message and source location.
*/
export function find_svelte_effect_diagnostics(code: string, filename: string) { ... }
Sources: AGENTS.md:133-138, AGENTS.md:144-154, modules/svelte-effect-runtime/src/diagnostics.ts:18-32
Import Organization
Imports are strictly grouped and sorted by line length in descending order to minimize visual noise.
Grouping Order
- Named imports:
{ ... } - Default imports
- Namespace imports:
* as
Within each group, a blank line is used as a separator, and lines are sorted so that longer lines appear above shorter ones.
Sources: AGENTS.md:179-195, CONTRIBUTING.md:63
Git Etiquette and Release Process
The project follows a centralized release model where all packages share the same semantic version.
Commit Guidelines
- Branches: Always create a branch for new work; never push to
masterwithout approval. - Messages: Use conventional prefixes (e.g.,
fix:,docs:,feat:). - AI identifiers: Do not include AI model or agent names in commit messages.
Versioning and Release
When releasing, the version must be bumped identically in four specific files:
modules/svelte-effect-runtime/package.jsonmodules/svelte-effect-runtime-grammars/package.jsonmodules/svelte-effect-runtime-language-server/package.jsonmodules/svelte-effect-runtime-vsix/package.json
Summary
The SER coding style emphasizes declarative syntax, proactive documentation, and strict visual organization. By adhering to these guidelines, developers ensure that the complex logic involved in Svelte-Effect transformations remains accessible and that the project's multi-package architecture stays synchronized.