diff --git a/docs/adr/0001-stop-sprite-when-method.ja.md b/docs/adr/0001-stop-sprite-when-method.ja.md deleted file mode 100644 index dea6f2eb9d9..00000000000 --- a/docs/adr/0001-stop-sprite-when-method.ja.md +++ /dev/null @@ -1,167 +0,0 @@ -# Stop using self.when, don't use reserve words - -- User Story: smalruby/smalruby3-gui#309 -- Status: accepted -- Deciders: takaokouji -- Date: 2023-01-02T05:05:45:29+0900 - -Sorry, this is written in Japanese. - -# self.whenからself.を取り除いたRubyの命令を検討する - -イベントカテゴリの `フラグが押されたとき` 、 `[スペース▼]キーが押されたとき` などの各種イベントに対応したブロック(以下、イベントブロック)は、`self.when(:flag_clicked) do ~ end` のように Ruby では `Sprite#when` メソッドにマッピングされる。 - -```ruby -# フラグが押されたとき -self.when(:flag_clicked) do -end - -# [スペース▼]キーが押されたとき -self.when(:key_pressed, "space") do -end - -# [音量▼] > (10) のとき -self.when(:greater_than, "loudness", 10) do -end -``` - -`self.when` には次の課題がある。 - -- Ruby では、publicなメソッドの呼び出しは通常は `self.` を省略するが、`when` は予約語であるため、常に `self.` を記述する必要がある -- Ruby では、予約語をメソッド名に使うことはできるが、それを推奨するといった説明はどこにもない - -イベントブロックは多用されるため、これが不自然なものであれば、スモウルビーを通じてRubyの文法を学習するときに問題となることを懸念している。 - -そこで、イベントブロックから Ruby の命令へのマッピングとして `self.when` ではない別の選択肢を検討する。 - -## 判断基準や制限 - -* Rubyの文法を自然に学べること -* Rubyの初学者に受け入れられるように入門書で扱うRubyの文法や仕組みを使うこと - * 現状の「予約語 when を上書きする」というのは中級者以上を想定したものだと認識している -* ブロックとRubyの相互変換処理の実装が簡単であること - * 前後の状態に依存したものは実装が大変 -* 文字のタイプ数が少ないこと -* 記号のタイプ数が少ないこと -* ブロックの英語表現に似たRubyの命令であること - -## 選択肢 - -* `when_%event_type%(%args%)` -* `When(:%event_type%, %args%)` -* `_when(:%event_type%, %args%)` -* `on(:%event_type%, %args%)` - -## 決定 - -**採用:** `when_%event_type%(%args%)` - -```ruby -# フラグが押されたとき -when_flag_clicked do -end - -# [スペース▼]キーが押されたとき -when_key_pressed("space") do -end - -# [音量▼] > (10) のとき -when_greater_than("loudness", 10) do # 省略形 when_gt(...) -end -``` - -* `on(:%event_type%, %args%)` と迷った -* 決め手は「メソッド名がブロックの英語表現と類似している」こと -* スモウルビーは、先生やメンターなどの指導者がいない状況でRubyの文法を学ぶことを想定しているため、ブロックを英語(English)表記にするだけでRubyの文法をほとんど学べている、というのは魅力的 - -## 各選択肢の良い点と悪い点 - -### `when_%event_type%(%args%)` - -```ruby -# フラグが押されたとき -when_flag_clicked do -end - -# [スペース▼]キーが押されたとき -when_key_pressed("space") do -end - -# [音量▼] > (10) のとき -when_greater_than("loudness", 10) do # 省略形 when_gt(...) -end -``` - -* `+` 増えた記号が `_` で減った記号が `:` なので+-0 -* `+` `self.`分、タイプ数が減る -* `+` メソッド名がブロックの英語表現と類似している - * ただし、引数まで考慮すると違和感がある。`when [loudness▼] > 10` が `when_greater_than("loudness", 10) do` -* `+` メソッドが分かれるのでRubyからブロックへの変換処理の実装が簡単になる -* `-` メソッドが増える - * `self.when` の場合は `when` メソッドのみだった - -### `When(:%event_type%, %args%)` - -```ruby -# フラグが押されたとき -When(:flag_clicked) do -end - -# [スペース▼]キーが押されたとき -When(:key_pressed, "space") do -end - -# [音量▼] > (10) のとき -When(:greater_than, "loudness", 10) do -end -``` - -* `+` `self.` を記述しなくてよい -* `+` `self.when` からの変更が少ない -* `-` Ruby にはメソッド名を大文字から始める習慣がないため、Rubyの初学者に誤った知識を与える可能性がある -* `-` Rubyの初学者がまったく動作の異なる予約語 `when` をこの When メソッドだと勘違いして覚えてしまう可能性がある - -### `_when(:%event_type%, %args%)` - -```ruby -# フラグが押されたとき -_when(:flag_clicked) do -end - -# [スペース▼]キーが押されたとき -_when(:key_pressed, "space") do -end - -# [音量▼] > (10) のとき -_when(:greater_than, "loudness", 10) do -end -``` - -* `+` `self.` を記述しなくてよい -* `+` `self.when` からの変更が少ない -* `-` ( `When` と同様に ) Ruby にはメソッド名を `_` から始める習慣がないため、Rubyの初学者に誤った知識を与える可能性がある -* `-` ( `When` と同様に ) Rubyの初学者がまったく動作の異なる予約語 `when` をこの When メソッドだと勘違いして覚えてしまう可能性がある - -### `on(:%event_type%, %args%)` - -```ruby -# フラグが押されたとき -on(:flag_clicked) do -end - -# [スペース▼]キーが押されたとき -on(:key_pressed, "space") do -end - -# [音量▼] > (10) のとき -on(:greater_than, "loudness", 10) do -end -``` - -* `+` `self.` を記述しなくてよい -* `+` `self.when` からの変更が少ない -* `+` `on` はイベントハンドラとして違和感がないメソッド名である - - Rubyだけでなく各種言語やライブラリでこのような用途として使われているという実績がある -* `+` タイプ数が少ない -* `-` メソッド名がブロックの英語表現とは異なる - * ブロックの英語表現は、 `when :flags: clicked` 、 `when [loudness▼] > 10` など。 diff --git a/docs/adr/0002-what-to-describe-as-adr.md b/docs/adr/0002-what-to-describe-as-adr.md deleted file mode 100644 index ea2fa636eb7..00000000000 --- a/docs/adr/0002-what-to-describe-as-adr.md +++ /dev/null @@ -1,58 +0,0 @@ -# What to describe as ADR and what not to describe - -- Status: accepted -- Deciders: takaokouji -- Date: 2023-01-02T10:10:41:40+0900 - -Sorry, this is written in Japanese. - -# なにをADRとして記述して、なにを記述しないのか - -ADRを記述することにしたのはいいのですが、すべての意思決定をADRとして記述するのは現実的ではありません。 - -そこで、なにを記述して、なにを記述しないのかを決めます。 - -## 判断基準や制限 - -* 続けられること -* スモウルビーは余暇をつかって開発しているため、作業時間の全体に限りがあること - -## 選択肢 - -* 10分で書けそうなものだけADRに記述する -* 1時間で書けそうなものだけADRに記述する -* 意思決定のすべてにADRを記述する - -## 決定 - -**採用:** 10分で書けそうなものだけADRに記述する - -* 続けられるのを優先した。 -* 10分で書けるもの、または10分で書ける程度のメモ書きを残すことにする -* 書き慣れてくると、10分で書ける内容が洗練されてくることを期待したい -* ADRのブランチやコミットメッセージは以下に決めた - * ブランチ名: `adr-%ファイル名から0001などの番号と拡張子を取り除いたもの%` - * 例: `adr-what-to-describe-as-adr` - * コミットメッセージ: `docs: adr %ファイル名から0001などの番号と拡張子を取り除いたもの% [skip ci]` - * 末尾の `[skip ci]` は必須 - * PRのタイトルもコミットメッセージと同じものにして、CIをスキップすること - -## 各選択肢の良い点と悪い点 - -### 10分で書けそうなものだけADRに記述する - -* `+` 簡単に書けることが前提なので続けられそう -* `-` 時間がかかりそうなものは中途半端な内容になったり、そもそもADRを残さなかったりする - -### 1時間で書けそうなものだけADRに記述する - -* `+` 10分で書けるものよりは、記録されている内容が増える -* `-` 手間がかかる -* `-` 面倒なので続かなくなる - -### 意思決定のすべてにADRを記述する - -* `+` 将来、なぜこうしたのか？を自分が知ることができる -* `+` なぜこうしたのかを他人が知ることができる -* `-` 手間がかかる -* `-` 面倒なので続かなくなる diff --git a/docs/adr/0003-test-for-interconverting-block-and-ruby.md b/docs/adr/0003-test-for-interconverting-block-and-ruby.md deleted file mode 100644 index 0a62f43afb5..00000000000 --- a/docs/adr/0003-test-for-interconverting-block-and-ruby.md +++ /dev/null @@ -1,70 +0,0 @@ -# Unit and Integration test for interconverting between "Code" and "Ruby" - -- User Story: smalruby/smalruby3-gui#309 -- Status: accepted -- Deciders: takaokouji -- Date: 2023-01-08T14:50:56+0900 - -Sorry, this is written in Japanese. - -# ブロックとRubyの相互変換の自動テストの実装方針 - -現在、ブロックとRubyの相互変換の自動テストは、次の2つのファイルに記載している。 - -- `test/unit/lib/ruby-to-blocks-converter/*.test.js` -- `test/integration/ruby-tab/*.test.js` - -前者はいわゆる単体テストで、すべてがNode.js上で実行されて軽くて速いが、Rubyからブロックへの変換処理のみが対象なので、一部しかテストできない。 - -後者はいわゆるシステムテストで、テストコードはNode.jsだが、処理の実行はヘッダレスChrome上で行うため、重くて遅いが、ブロックとRubyとの相互変換処理が対象なので、全体をテストできる。 - -どちらの自動テストもメンテナンスし続けられればベストだが、作業時間が限られるため、現実的な方法で自動テストをメンテナンスしていきたい。 - -## 判断基準や制限 - -* 十分にテストできること - * デグレを検知できること -* テストの実装が簡単であること -* 実行時間が短いこと - -## 選択肢 - -* (現行) 単体テストとシステムテストの両方を実装する -* 単体テストのみ実装する -* システムテストのみ実装する -* 単体テストはエラーケースのみ、システムテストはそれ以外 - -## 決定 - -**採用:** 単体テストはエラーケースのみ、システムテストはそれ以外 - -* 「システムテストのみ実装する」と迷った -* 有限時間でできるのはこれしかなかった -* コーナーケースのチェックが甘くなってしまうため、手動テストで確認すべきところは文章などで残しておかないといけない - * 単体テスト側のソースコードにコメントとして書いていくことにする (時間があれば単体テストとして実装する余地を残すため) - -## 各選択肢の良い点と悪い点 - -### 単体テストとシステムテストの両方を実装する - -* `+` 単体テストでRubyからブロックへの変換処理のコーナーケースを高速にテストでき、システムテストで俯瞰的なテストができ、十分にテストできる -* `-` ブロックの内部構造を把握する必要があり単体テストの実装が難しく、時間がかかる - -### 単体テストのみ実装する - -* `+` 単体テストでRubyからブロックへの変換処理のコーナーケースを高速にテストできる -* `+` システムテストを実装する必要がなく、作業時間が短縮できる -* `-` ブロックの内部構造を把握する必要があり単体テストの実装が難しく、時間がかかる -* `-` ブロックからRubyへの変換処理のテストを実装できず、デグレが発生する可能性が高いし、毎回、手作業でRubyへの変換処理のテストをする必要がある - -### システムテストのみ実装する - -* `+` 単体テストを実装する手間がかからない -* `+` システムテストの実装そのものは簡単 -* `-` コーナーケースを実装する場合にテストの実行時間が長くなってしまう。結果として、コーナーケースは最低限の実装になったり、実装しなかったりする - -### 単体テストはエラーケースのみ、システムテストはそれ以外 - -* `+` エラーケースのみのRubyからブロックへの変換処理の単体テストは実装が簡単 -* `+` システムテストでは、最も煩雑なエラーケースを扱わないことで、すべてのケースを実装する場合に比べて、実行時間が短くできる。想定では50%くらい違う。 -* `-` Rubyからブロックへの変換処理の正常系のうち、コーナーケースのチェックが甘くなってしまい、細かい処理でデグレが発生する可能性がある