Coding

Coding Standards

Commenting

Commenting is critical. Comments explain what we are doing AND why we are doing it that way — capturing mindset and design decisions. This helps spot shortcomings while coding and lets other devs understand the work.

Comment style — the comment sits directly above the code it describes, separated from the next block by a blank line:

// comment here
first_code

// second comment here
second_code

Naming Conventions

Step 1 — check if the codebase already has an established convention. If it does, follow it exactly. Do not introduce a different style, even if it looks better.

Step 2 — if no convention exists, ask the operator:

"Which naming style should I use?

• Standard — the default community norms for this language (camelCase/kebab-case for JS, snake_case for Python). Good when an AI agent is writing the code autonomously.
• Improved — a more readable hybrid that keeps underscores for separation but uses capitalization to signal nouns and significant concepts. Better when the developer is reading the code themselves."

For the improved version, see: Improved_Camel_Snake convention

For standard language conventions, see the language guides:

• JS / TS
• Markdown & non-code files

File & Folder Structure

Ideal strucutre, which you might not be able to always obtain: Organize by feature, not by type. Each feature gets its own folder with one clear entry file — this is the face of the feature. All supporting code (helpers, types, queries, etc.) lives in subfiles alongside it. You read the entry file and know what the feature does; you follow the links for implementation detail.

user/
  user.ts       ← entry file — public interface of the feature
  queries.ts    ← supporting file
  helpers.ts    ← supporting file
  types.ts      ← supporting file

• One file, one clear purpose. If a file is doing two things and it is already big, try to get two files out of it.
• Split into a subfolder whenever a group of subfiles grows large enough to warrant it (max 300 lines per file, keep comments).
• Shared/cross-cutting code gets its own clearly named folder (e.g. shared/, utils/, core/).
• A dedicated helpers file is valid — it can contain small functions that don't clearly belong anywhere else and don't need to share the same purpose. Creating subfolders for every small function is overkill.

Universal Rules — All Languages

• Obvious code: make inputs and outputs crystal clear. Avoid unnecessary abstractions — keep methods, classes, and functions straightforward.
• Single responsibility: one file, one clear purpose. If a function doesn't clearly belong anywhere, it goes in a helpers file within the relevant feature folder.
• No deep nesting: use early returns and guard clauses to keep logic flat.
• Max 300 lines per file — comments do not count toward this limit and cannot be removed to reach it.
• Never remove comments — comments stay unless the logic they describe has changed or removal is explicitly requested.
• No fallbacks — hard breaks only. If things crash, we need to experience those crashes.