Ruby ↔ ブロック変換ディレクティブ形式の決定

[takaokouji]

Context and Problem Statement - コンテキストと問題の説明

Issue #527「Ruby の print, puts, p を命令ブロックに変換できるようにする」の実装において、Ruby → ブロック → Ruby の可逆変換を実現するため、ブロックにメタ情報をコメントとして付加する必要が生じました。

この際、将来の拡張性を考慮したディレクティブ形式を決定する必要があります。

• Ruby変換情報だけでなく、将来的に設定情報やヒント情報なども扱う可能性がある
• 複数の言語（Python, JavaScriptなど）への対応も視野に入れる必要がある
• 教育現場で使用されるため、シンプルで理解しやすい形式が望ましい

関連リンク:

• Issue #527: Ruby の print, puts, p を命令ブロックに変換できるようにする #24
• PR #528: feat: use new meta-comment format @ruby:method: for print/puts/p smalruby3-gui#528

Decision Date - 決定日付

2026/01/18

Decision Makers - 意思決定者

@kouji (ユーザー)
Claude Code (レビューアー・提案者)

Decision Drivers - 決定要因

• 頻度の最適化: Ruby変換情報は頻繁に使用されるため、短い記法が望ましい
• 拡張性: 将来的な機能追加に対応できる柔軟な設計
• 名前空間の安全性: 他のツールやRuby公式との衝突を避ける
• 直感性: スモウルビーの本質（Ruby版Scratch）に合致した形式
• 教育的配慮: 小学生でも理解可能なシンプルさ

Considered Options - 検討した選択肢

1. @smalruby:CATEGORY:VALUE - スモウルビー統一形式
2. @ruby:VALUE - Ruby変換専用形式
3. ハイブリッド形式 - 用途別プレフィックス
4. JSON形式 - 構造化データ形式

Decision - 決定

内容

提案C（ハイブリッド形式）を採用

@ruby:CONVERSION_INFO          # Ruby変換情報（頻繁、短縮）
@smalruby:CATEGORY:VALUE       # スモウルビー機能（稀、明示的）

具体的な実装:

@ruby:method:print
@ruby:method:puts
@ruby:method:p

理由

1. 実用性: 最も頻繁に使う Ruby変換は短く @ruby: とすることで、タイプ量を削減し、可読性を向上
2. 拡張性: スモウルビー独自機能は @smalruby: を使用することで、機能の分類と拡張が容易
3. 直感性: スモウルビー = Ruby という本質に合致し、理解しやすい
4. 柔軟性: 将来の多言語対応（@python:, @javascript: など）も可能
5. 名前空間の分離: Ruby変換とスモウルビー機能で名前空間を分けることで、用途が明確

Consequences - 結果

Good

• Ruby変換の簡潔性: @ruby:method:print は @smalruby:ruby:method:print より短く、頻繁な使用に適している
• 拡張の一貫性: スモウルビー機能は @smalruby: で統一され、一貫性がある
• 多言語対応の容易さ: @python:, @javascript: などを追加しやすい
• 教育的: シンプルで理解しやすい形式

Neutral

• 2つのプレフィックス: @ruby: と @smalruby: の使い分けを理解する必要がある

Bad

• 完全な一貫性ではない: すべて @smalruby: に統一した場合と比べると、若干の不統一感がある

Confirmation - 確認

• Issue #527 にディレクティブ形式の決定を記載
  • https://github.com/smalruby/smalruby3-gui/issues/527#issuecomment-3764870322
• PR #528 のコードを @ruby:method:print 形式に更新
• ADR を GitHub Discussions に記録
• 実装完了後、labelを ADR-accepted に変更

Pros and Cons of the Options - 選択肢の長所と短所

選択肢1: @smalruby:CATEGORY:VALUE

すべてのディレクティブを @smalruby: で統一する形式。

• Good
  • 完全な一貫性がある
  • 名前空間の衝突リスクが最小
• Bad
  • Ruby変換で @smalruby:ruby:method:print と長くなり、頻繁な使用に不向き
  • スモウルビー = Ruby という本質が薄れる

選択肢2: @ruby:VALUE

すべて @ruby: で統一する形式。

• Good
  • 非常にシンプル
  • スモウルビー = Ruby の本質に合致
• Neutral
  • Ruby変換専用で、拡張性が制限される
• Bad
  • Ruby以外の機能（設定、ヒント等）に対応できない
  • 将来的に @python:, @config: など複数のプレフィックスが乱立する可能性

選択肢3: ハイブリッド形式（採用）

@ruby: と @smalruby: を用途別に使い分ける形式。

• Good
  • Ruby変換は短く @ruby:method:print
  • スモウルビー機能は明示的に @smalruby:config:debug
  • 拡張性と実用性のバランスが最適
  • 多言語対応が容易
• Neutral
  • 2つのプレフィックスの使い分けルールが必要
• Bad
  • 完全な一貫性ではない（@smalruby: に統一した場合と比較）

選択肢4: JSON形式

@smalruby:{"type":"ruby","method":"print"} のような構造化形式。

• Good
  • 複雑な情報を格納可能
  • パースが標準的
• Bad
  • 人間が読みにくい
  • 教育現場では複雑すぎる
  • タイプ量が多い

More Information - 詳細情報

実装予定

• 2026/01/18 から実装開始
• PR #528 で @ruby:method:print 形式に更新

将来の拡張例

# Ruby変換情報
@ruby:method:print
@ruby:method:custom_name
@ruby:class:ClassName

# スモウルビー機能
@smalruby:config:auto-save:on
@smalruby:hint:初心者向けヒント
@smalruby:level:beginner
@smalruby:version:3.1.0

# 多言語対応（将来）
@python:function:print
@javascript:method:console.log

参考情報

• Python: # type:, # noqa
• TypeScript: // @ts-ignore
• Kotlin: @Suppress, @JvmStatic

見直しの条件

• 多言語対応を本格的に開始する際
• ディレクティブの種類が大幅に増加した際
• ユーザーからのフィードバックで混乱が報告された際