Foundation Style guide

Coding Conventions

Klyn stays readable when a codebase follows a few consistent rules about naming, file layout, typing, and API surface design. These conventions are not mere aesthetics; they reduce ambiguity in a statically typed language with explicit package structure.

Naming
  • Use UpperCamelCase for classes, interfaces, enums, and annotations.
  • Use lowerCamelCase for functions, methods, variables, and properties.
  • Use a leading underscore for private backing fields.
  • Write constants in UPPER_SNAKE_CASE.
  • Omit static on class constants: const is intrinsically static.
  • Use const for class-owned values, including values created once at runtime.
  • Use readonly for constructor-initialized instance fields and getter-only properties.
Files and Packages
  • Keep one public top-level type per file.
  • Keep the file name equal to that public type name.
  • Keep every named package aligned with the directory structure, one segment per directory.
  • Use the default package only for small, self-contained scripts and samples.
  • Prefer explicit imports and fully qualified names when ambiguity would hurt readability.
Typing Style

Inference is good for obvious local values, but public APIs, object properties, and important boundary variables should stay explicitly typed. 

# Good local inference
total = 0

# Better explicit public surface
public property timeoutMs as Int = 1000
Prefer Properties Over Exposed State

Use a property when a value belongs to the public surface, even if the first implementation is simple. This keeps room for validation and future evolution.

Formatting Blocks
  • Indent with spaces, not tabs.
  • Keep one logical statement per line.
  • Use multi-line calls when they improve readability, especially for constructors and data literals.
  • Prefer short, explicit blocks over clever one-liners when logic becomes non-trivial.
Document Public APIs

Public types and members benefit from KlynDoc-style comments that describe the element, its parameters, return value, thrown exceptions, and a realistic usage example.

Error Messages and Exception Discipline

When throwing exceptions, choose messages that explain the failed condition precisely. In a statically typed language, clear errors matter because they guide both debugging and API usage.