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.
  • Reserve const names for stable values that are truly immutable.
Files and Packages
  • Keep one public class per file.
  • Keep the file name equal to that public class name.
  • Keep the package declaration aligned with the directory structure.
  • 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.