# Coding Conventions

**Analysis Date:** 2026-02-23

## Naming Patterns

**Terraform Files:**
- `main.tf` - Primary resource definitions and module calls
- `terragrunt.hcl` - Stack-specific Terragrunt configuration
- `variables.tf` - Variable declarations for a stack
- `providers.tf` - Generated by Terragrunt root `terragrunt.hcl`
- `backend.tf` - Generated by Terragrunt for state backend configuration

**Terraform Variables:**
- snake_case for variable names: `var.tls_secret_name`, `var.dbaas_root_password`
- snake_case for resource names: `resource "kubernetes_namespace" "nextcloud"`
- snake_case for local values: `local.tiers`
- UPPERCASE for environment-like globals in shell: `KUBECONFIG_PATH`, `PASS_COUNT`

**Resource/Module Names:**
- kebab-case for Kubernetes resources: `nextcloud`, `whiteboard`, `kms-web-page`
- Leading underscore for prefixed resource names (internal/private pattern): resource names with underscores are module-internal
- Descriptive names matching functionality: `kubernetes_namespace`, `kubernetes_deployment`, `helm_release`

**Shell Functions:**
- snake_case for function names: `parse_args()`, `count_lines()`, `check_nodes()`
- CamelCase for utility color variables: `RED`, `GREEN`, `YELLOW`, `BLUE`, `BOLD`, `NC`

**Go Package/Test Names:**
- Package-level test functions: `TestContainsVideoMarkers()`, `TestIsDirectVideoContentType()`
- Table-driven test pattern with struct fields: `name`, `body`, `ct`, `want`

## Code Style

**Terraform Formatting:**
- Use `terraform fmt -recursive` for consistent formatting
- No explicit linter/formatter config file (tflint/terraform-lint not present)
- Indentation: 2 spaces (standard Terraform convention)
- Multi-line strings use heredoc syntax: `<<EOT ... EOT` for YAML/config blocks

**Bash Script Style:**
- Shebang: `#!/usr/bin/env bash`
- Safety flags: `set -euo pipefail` (exit on error, undefined vars, pipe failures)
- Comments use `# ---` separator for section dividers
- Comments use `# ---` for grouping related variables/functions
- One-liner functions defined as: `function_name() { [[ condition ]] && action; }`
- Multiline functions use explicit function body with local keyword for variables

**Terraform Style:**
- Comments for major sections use `# =============================================================================`
- Comments for subsections use `# --------- -------`
- Inline comments explain why, not what: `# anything secret is fine` (explaining arbitrary choice)
- Module calls include comments above describing purpose: `# --- Core ---`, `# --- dbaas ---`

## Import Organization

**Terraform:**
- Locals (tier definitions) defined at top of main.tf
- Variables declared in order: core/required first, then by feature area (dbaas, traefik, etc.)
- Modules called after variables, grouped by functional area with comment headers
- Resources defined after modules

**Go:**
- Standard imports from `testing` package
- No grouping (single simple import)

**Bash:**
- Source definitions at top (colors, globals, helper functions)
- Argument parsing in dedicated `parse_args()` function
- Main logic organized by check sections with `section()` calls

## Error Handling

**Terraform:**
- No explicit error handling (declarative; errors cause apply failure)
- Dependency management via `depends_on` for explicit ordering
- `dependency` blocks in terragrunt for cross-stack dependencies
- `skip_outputs = true` used when only needing ordering, not outputs

**Bash:**
- Inline error checks: `command 2>&1) || { fail "message"; return 0; }`
- `set -euo pipefail` prevents silent failures and undefined var issues
- Error status captured: `$?` implicit via `||` pattern
- Graceful degradation with fallback values or skip-able steps

**Go:**
- Standard testing error reporting: `t.Errorf()` with formatted messages
- Table-driven test pattern allows multiple related test cases
- Error messages include actual vs expected: `got = %v, want = %v`

## Logging

**Framework:** Not formally configured; uses `echo` and `echo -e` for output

**Bash Logging Patterns:**
- Color-coded output with status prefixes: `${BLUE}[INFO]${NC}`, `${GREEN}[PASS]${NC}`, `${YELLOW}[WARN]${NC}`, `${RED}[FAIL]${NC}`
- Helper functions: `info()`, `pass()`, `warn()`, `fail()` - each increments counters and respects `--quiet` flag
- Section headers: `section()` for verbose output, `section_always()` for always-shown sections
- Conditional logging: functions check `$JSON`, `$QUIET` flags and skip output as needed
- JSON output option available via `json_add()` for machine-readable logging
- Detail strings accumulated in variables for final reporting

**Terraform Logging:**
- Relies on Terraform's built-in CLI output
- Human-readable variable values in descriptions (Terraform renders these on errors)

## Comments

**When to Comment:**

Terraform:
- Section dividers: Major logical groups separated by `# =============================================================================`
- Feature group headers: `# --- Feature Name ---` before variable/module blocks
- Commented-out code: Temporarily disabled resources/modules include explanation (e.g., "Do not use until issue #X is solved")
- Clarifying arbitrary choices: `# anything secret is fine` explains non-obvious variable usage

Bash:
- Function-level comments: Each check function has purpose on first line
- Complex logic: Comments before conditional blocks explain intent
- Inline comments for edge cases: `# Skip nodes where metrics are not yet available`
- Header comments: Scripts include usage documentation at top

**JSDoc/TSDoc:**
- Not used in this codebase (Terraform, Bash, Go only)

## Function Design

**Size:**
- Terraform modules typically 20-50 lines for simple services, variable declaration blocks 30-100+ lines
- Bash functions average 20-40 lines, check functions 10-30 lines
- Go test functions 10-60 lines (table + loop)

**Parameters:**
- Terraform: via `variable` declarations and module input variables
- Bash: positional parameters passed via `$1`, `$2`, etc. with validation in `parse_args()`
- Go: test functions accept `*testing.T` parameter

**Return Values:**
- Terraform: no explicit returns; resource state is the "return"
- Bash: `return 0` for success, implicit via `echo` output for values, status codes for error handling
- Go: functions tested for boolean returns or calculated values

**Variables:**
- Terraform: module variables, locals, and resource attributes (computed values)
- Bash: Global state tracked via counters (`PASS_COUNT`, `WARN_COUNT`, `FAIL_COUNT`), local variables in functions with `local` keyword
- Go: table-driven tests use struct fields (no getter/setter pattern)

## Module Design

**Exports:**
- Terraform: outputs typically omitted unless another stack depends on them (implicit via dependency blocks)
- Modules called with `source = "./modules/<name>"` or `source = "../../modules/kubernetes/<name>"`
- Module version pinning used for Terraform registry modules: `version = "0.1.5"`

**Barrel Files:**
- Not applicable (no aggregating re-exports in this codebase)
- Directories: `stacks/<service>/` is a unit, `stacks/platform/modules/<service>/` groups related modules

**Module Organization:**
- Single responsibility per module directory
- Each module typically contains: `main.tf` (resources) and optional `variables.tf` for input variables
- Shared Kubernetes utility modules in `modules/kubernetes/`: `ingress_factory/`, `setup_tls_secret/`
- Platform services grouped in `stacks/platform/modules/<service>/`

## Special Patterns

**Locals for Configuration:**
- Tier definitions centralized as map in locals (each service defines same tiers locally)
  ```hcl
  locals {
    tiers = {
      core    = "0-core"
      cluster = "1-cluster"
      gpu     = "2-gpu"
      edge    = "3-edge"
      aux     = "4-aux"
    }
  }
  ```
- Tier applied to `kubernetes_namespace` labels and `priority_class_name` for resource governance

**Inline Config Blocks:**
- YAML/config data stored in `<<EOT ... EOT` heredoc blocks within `data` maps
- Example: MetalLB address pool config in ConfigMap data

**File Inclusion:**
- `templatefile()` used for dynamic YAML values: `templatefile("${path.module}/chart_values.yaml", { var1 = value })`
- `file()` used for static file content in ConfigMap data

---

*Convention analysis: 2026-02-23*