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: 最初のメソッド以降にフィールドを追加すること（リンタ警告／厳格モードでエラー）。

良い例

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

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

悪い例（NG）

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

ツール

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

Examples

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/.