Coding conventions

Conventions for writing code across all Jersal projects. These apply regardless of the specific framework or project.

Language preferences

Priority	Language	Use case
Primary	TypeScript	Frontend, backend, tooling, scripting
Secondary	Python	Data processing, ML, infrastructure tooling (MkDocs)
Secondary	C#	When required by integration targets

TypeScript is the default choice. Use Python or C# when there's a specific reason (e.g., a library ecosystem, integration requirement, or team expertise).

TypeScript

Strict mode

All TypeScript projects use strict mode. The tsconfig.json should include:

{
  "compilerOptions": {
    "strict": true
  }
}

Module system

• Target: ES2022 or later
• Module resolution: bundler
• Output: ES modules

Formatting and linting

To be established

Specific ESLint and Prettier configurations are being standardized. Until then, use the configurations provided by the project template.

Recommended baseline:

• Use consistent indentation (2 spaces for TypeScript)
• Prefer const over let, avoid var
• Use explicit return types on exported functions
• Prefer named exports over default exports

Infrastructure code (Terraform)

HCL conventions

• Use snake_case for all Terraform identifiers (resources, variables, outputs)
• Pin provider versions with pessimistic constraints (~>)
• Pin Terraform version with minimum constraint (>=)
• Use modules for any resource pattern that appears in more than one environment
• Validate variable inputs where possible (see sku_name validation in postgres-flex)

Variable defaults

• Provide sensible defaults for non-sensitive variables
• Never provide defaults for sensitive variables (passwords, tokens)
• Use sensitive = true for all secret variables

General principles

1. Explicit over implicit -- Type annotations, named parameters, clear variable names
2. Fail fast -- Validate inputs, use strict mode, catch errors early
3. Small modules -- Keep modules, functions, and components focused on a single responsibility
4. No dead code -- Remove unused imports, variables, and functions