47f4ca0e44
## Summary Documented the "init block vs fields-at-top" design discussion as a valuable example of AI-human collaboration in language design. ## Changes ### Paper G (AI Collaboration) - Added field-declaration-design.md documenting the entire discussion flow - Showcased how complex init block proposal evolved to simple "fields at top" rule - Demonstrates AI's tendency toward complexity vs human intuition for simplicity ### Paper H (AI Practical Patterns) - Added Pattern #17: "Gradual Refinement Pattern" (段階的洗練型) - Documents the process: Complex AI proposal → Detailed analysis → Human insight → Convergence - Field declaration design as a typical example ### Paper K (Explosive Incidents) - Added Incident #046: "init block vs fields-at-top incident" - Updated total count to 46 incidents - Shows how a single human comment redirected entire design approach ## Design Decision After analysis, decided that BoxIndex should remain a compiler-internal structure, not a core Box: - Core Boxes: User-instantiable runtime values (String, Integer, Array, Map) - Compiler internals: BoxIndex for name resolution (compile-time only) - Clear separation of concerns between language features and compiler tools ## Philosophy This discussion exemplifies key principles: - The best design needs no explanation - Constraints provide clarity, not limitation - "Everything is Box" doesn't mean "compiler internals are Boxes" - AI tends toward theoretical completeness; humans toward practical simplicity 🐱 Sometimes the simplest answer is right in front of us\!
100 lines
3.3 KiB
Markdown
100 lines
3.3 KiB
Markdown
# 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/`.
|