Code Style

Campfire code style

Conventions for matching the pre-established style of this codebase. Architecture, the module graph and the build are in the root CLAUDE.md and the per-module ones; this skill is about how the code reads.

License header

• Every new file starts with the MPL-2.0 header, copied verbatim from a sibling file: .kt, .kts, .xml (comment syntax), .md (HTML comment), .gitignore-style config (# lines). No exceptions — a new file without it is an incomplete change.
• The year range stays as the siblings have it (2017-2026); don't invent a new one per file.

Comments

Campfire is a heavily commented codebase, but only in one direction: comments carry the why, never the what. The bar for a comment is "a reader who understands Kotlin and Compose would still get this wrong or undo it".

• Never narrate routine code. No comment above a remember, a when, a mapper, a LaunchedEffect that does the obvious thing, and no section-divider banners. If the code says it, the comment is noise.
• Do comment the load-bearing decision. Platform quirks, ordering constraints, API misbehavior, why a state is eager instead of WhileSubscribed, why a sheet clears visibleDialog itself, why a file input is wider than it looks like it should be. These are exactly the comments the codebase already has, and the ones a future "simplification" would otherwise delete.
• Write them as prose, in full sentences, in the voice of the existing comments and CLAUDE.md files: specific, technical, unhurried, several lines when the reason needs several lines. Wrap at the same width as the surrounding file (~130 columns). Not telegraphic fragments, not "// HACK".
• Never write archaeology. Once a fix has landed the code is simply how it works; no "this used to crash because…", no postmortems, no bug/ticket numbers. Where an unintuitive solution invites being optimized away, state the constraint that makes it necessary, in the present tense.
• No TODOs, no commented-out code. Delete it instead.

Documentation (KDoc)

• Declaration-level documentation is always KDoc (/** … */), never a // block — including on internal and private declarations. // comments are for statements inside a function body.
• api modules carry the contract. Interfaces in :data:source:*:api, :data:repository:api, :domain:api and the public surface of :chordpro are documented with KDoc that explains the rules a second implementation must honor (see SyncProvider for the tone): what the type is for, what is opaque, what may throw, what the caller must not assume. @param only where the parameter is not self-explanatory.
• implementation modules are documented by naming and structure, plus a class-level KDoc where a class's job isn't obvious from its name. Don't KDoc every member of an Impl.
• Keep KDoc in sync when you change a signature or its behavior; a stale KDoc is worse than none.

Formatting

• Always use trailing commas on the last element of any multi-line comma-separated list — function parameters and arguments, constructor parameters, collection literals, enum entries, when with multiple guards. This keeps diffs minimal and reordering clean.
• The whole codebase has them, so a list without one is an oversight rather than an older style. The closing bracket decides: a ) or ] that starts a line of its own ends a list that wants a trailing comma; one that sits at the end of the last element's line does not. A parameter list broken across lines counts even with a single parameter in it, since a second one is the expected next edit — but a single-argument call written that way does not, and neither does a js("""…""") block.
• enum entries follow the same rule, except where the list ends in a ; because members come after it. A when branch with several conditions keeps the last one on the arrow's line, so there is nothing to put a comma after.
• Expression bodies wherever the function is one expression, including Composables that are a single layout call (private fun ScreenSurface(...) = Surface(...)) and one-line overrides that just delegate.
• Match the surrounding file's indentation, import order and idiom rather than reformatting to a personal preference. Don't reorder imports of files you touch.
• Named arguments for anything where the call site would otherwise be a row of positional values — Koin wiring, use case invocations, multi-parameter Composables.

Kotlin Multiplatform rules

• commonMain stays JVM-free: no java.*, no KoinJavaComponent, no JVM-only libraries. Use kotlin.uuid.Uuid, androidx.compose.ui.text.intl.Locale, KoinPlatform.getKoin() and import kotlinx.coroutines.IO for Dispatchers.IO.
• Platform behavior goes into androidMain / desktopMain / iosMain / wasmJsMain behind expect/actual — all four actuals, in the same change. A new expect that only three platforms implement does not build.
• Implementation classes are internal and named <Interface>Impl; Compose components in :presentation are internal too. Use cases are operator fun invoke.
• New Koin bindings go into the module's own top-level Module.kt, nowhere else.
• Cross layers through the mapper/ packages; never leak a document/entity type upwards.

Compose

• modifier: Modifier = Modifier is the first parameter of a Composable that takes one — this repo's order, even though the Compose guidelines say otherwise. Follow the repo.
• A Composable reads as a short list of named children. When a body grows several distinct visual groups, extract each into its own private @Composable named for what it is in the UI (SongFilters, SectionHeader), not for where it sits. A single focused widget needs no extraction.
• Extraction must not change the rendered output: don't add a Row/Column/Box a group didn't have, don't drop one it relied on, and apply parent-scope modifiers (Modifier.weight) at the call site.
• Material 3 Expressive only (org.jetbrains.compose.material3). Never import androidx.compose.material (M2). Icons are vector drawables in composeResources/drawable/, loaded with painterResource and passed around as Painter.
• Nothing appears or disappears abruptly: new UI states animate in and out the way the neighboring screens' empty/error states do.