hakorune/docs/guides/style-guide.md

# Nyash Style Guide (Phase 15)

Goals
- Keep Nyash sources readable and structured. Favor simple, predictable formatting compatible with reversible formatting (nyfmt PoC).

Formatting
- Indent with 2 spaces (no tabs).
- Braces: K&R style (opening brace on the same line).
- Max line length: 100 characters (soft limit).
- One statement per line. Use semicolons only when placing multiple statements on one physical line.
- Blank lines: separate top‑level `box` declarations with one blank line; no trailing blank lines at file end.

Statements and ASI
- Newline is the primary separator. See `reference/language/statements.md`.
- Do not insert semicolons before `else`.
- When breaking expressions across lines, break after an operator or keep the expression grouped.

using / include
- Place all `using` lines at the top of the file, before code.
- One `using` per line; no trailing semicolons.
- Sort `using` targets alphabetically; group namespaces before file paths.
- Prefer `as` aliases for readability. Aliases should be `PascalCase`.
- Keep `include` adjacent to `using` group, sorted and one per line.

Naming (conventions for Nyash code)
- Boxes (types): `PascalCase` (e.g., `ConsoleBox`, `PathBox`).
- Methods/functions: `lowerCamelCase` (e.g., `length`, `substring`, `lastIndexOf`).
- Local variables: concise `lowerCamelCase` (e.g., `i`, `sum`, `filePath`).
- Constants (if any): `UPPER_SNAKE_CASE`.

Structure
- Top‑to‑bottom: `using`/`include` → static/box declarations → helpers → `main`.
- Keep methods short and focused; prefer extracting helpers to maintain clarity.
- Prefer pure helpers where possible; isolate I/O in specific methods.

Box layout
- フィールドは box 本体の先頭にまとめる（先頭ブロック）。
- 先頭フィールド群の後ろはメソッドのみを記述する（`birth` を含む）。
- フィールド間の空行・コメントは許可。アノテーション（将来追加予定）もフィールド行の直前/行末を許可。
- NG: 最初のメソッド以降にフィールドを追加すること（リンタ警告／厳格モードでエラー）。

良い例
```nyash
box Employee {
  // データ構造（フィールド）
  name: StringBox
  age: IntegerBox
  department: StringBox

  // ここからメソッド
  birth(n, a, d) { me.name = n; me.age = a; me.department = d }
  promote() { }
}
```

悪い例（NG）
```nyash
box Bad {
  id: IntegerBox
  method1() { }
  name: StringBox  // ❌ フィールドはメソッドの後に置けない
}
```

ツール
- 警告: 既定は警告（`NYASH_CLI_VERBOSE=1` で詳細を表示）。
- 厳格化: `NYASH_FIELDS_TOP_STRICT=1` でエラーに昇格（Runnerでチェック）。

Examples
```nyash
using core.std as Std
using "apps/examples/string_p0.nyash" as Strings

static box Main {
  escJson(s) {  // lowerCamelCase for methods
    local out = ""
    local i = 0
    local n = s.length()
    loop(i < n) {
      local ch = s.substring(i, i+1)
      if ch == "\\" { out = out + "\\\\" }
      else if ch == "\"" { out = out + "\\\"" }
      else { out = out + ch }
      i = i + 1
    }
    return out
  }

  main(args) {
    local console = new ConsoleBox()
    console.println("ok")
    return 0
  }
}
```

CI/Tooling
- Optional formatter PoC: see `docs/tools/nyfmt/NYFMT_POC_ROADMAP.md`.
- Keep smoke scripts small and fast; place them under `tools/`.