このトピックでは、可読性の高いプログラムの書き方について研究します。
例えば「変数、リスト、定義ブロックの命名のルールについて」、「よいコメントの書き方とは」などです。
可読性について考えることはScratch初心者から上級者、他言語のプログラマーまで大きなメリットがあります。
ぜひ、このトピックで一緒に話し合いましょう！



可読性とは
「可読性？そんなの知ってるよ」という人は適当に読み飛ばしてください。
プログラミングにおける可読性とは、「プログラムがどれくらいわかりやすいか」です。
では、可読性の低いプログラムを見てみましょう。

when green flag clicked
[変数A v] を [100] にする
(10) 回繰り返す //お腹すいたな―
[変数A v] を (1) ずつ変える
もし <(1)=(1)> なら
((変数A)-(100)) と (2) 秒言う
end
end

このようなプログラムはとてもわかりづらいですね。理由は

• 変数Aが何をするものなのかが名前からわからない。(わかりやすい変数命名)
  
• 「お腹すいた」というコメントは必要がない。(わかりやすいコメント)
  
• 1=1は必ず正しくなるから、「もし…なら…文」で囲う必要がない。(やけに深いネスト)
  
• 変数Aを最終的に-100でしか使わないのなら、はじめから-100した値にするべき。(謎の値設定)
  

では、直したコードを見てましょう。

when green flag clicked
[繰り返し v] を [1] にする
(10) 回繰り返す
(繰り返し)と (2) 秒言う//1~10までを出力します。
[繰り返し v] を (1) ずつ変える
end

一気にわかりやすくなりましたね。
このようにして、プログラムの可読性を上げることができます。

早速乗らせていただきます
僕のプラットフォーマーでは、定義を多く使っていますが、全て、「横移動」「落ちた」「抵抗(このプラットフォーマーでは慣性の法則を使っていたので)」など、わかりやすい名前にしています。
常識かもしれませんが、「何をしているか」がわかりやすい名前にする命名規則だといいと思います。
あっ、全部定義です…

まずは、「変数命名のルール」について考えたいです。
例えば、繰り返し変数のindex、i、k、nなどはたくさん使うことがあるでしょうが、並列処理中に同じ変数を変更してしまうと問題があります。
自分は定義ブロックを活用するときには、定義ブロックを使う上での変数は「このスプライトのみ」の変数にして、

(定義ブロックのわかり易い名前.変数名)

のようにしています。また、返り値なんかは

(定義ブロックのわかり易い名前.!return)

なんかにして、「!」を一番初めにおいて、上に来るような工夫をしています。
他に「こんな工夫もあるよ～」みたいなのはありますか？

yu-yu0202 wrote:

僕のプラットフォーマーでは、定義を多く使っていますが、全て、「横移動」「落ちた」「抵抗(このプラットフォーマーでは慣性の法則を使っていたので)」など、わかりやすい名前にしています。

なるほど。まあ、自分でみてわかるならいい気もしますが、
「横移動」「落ちた」「抵抗」だと、すこし命名が抽象的すぎるかなという気がします。
「横移動」→「xの速さ」、「x speed」
「抵抗」→「摩擦」、「friction」
みたいな感じにすればもっとわかりやすくなると思います。(「抵抗」は基本的に定数になるので、それも示せたらいいですが)
特に、「落ちた」は「落ちている」(地面に触れていないか)なのか「落ちるスピード」(y軸方向の速さ)なのかが分かりづらいというのがある気がします。
真偽値のイメージなら「is falling?」などにすればいい気がしますね。
定義の話でしたか。読み間違えていました。

#3
なるほど。「!」を使うという手もありましたか！

私は最近、その変数が扱う値の種類を変数名に含めるようにしていますね。

(player1_int_score)
(player1_string_name)

Scratchは動的型付けを使用しているので型の概念はありませんが、こうすることで変数の代入に関する人的ミスを可能な限り減らしています。

コードプログラムの言語では、定数であってもほぼすべて定義しますが、Scratchの場合はどうなのでしょうか。
皆さんの意見を聞きたいです。

私は、かなり多くの箇所でその定数を使うのであれば分かりやすくなっていいと思いますが、数カ所のみとなると変数欄を圧迫してかえって分かりにくくなってしまうのではないか、と思っています。

適当な例：画像の大きさを変更する場合(Python/Scratch)
※すいません、Pythonのプログラムを書こうとしたらうまく投稿できませんでした。画像で投稿します。

[画像1の大きさ v] を [150] にする
大きさを (画像1の大きさ) % にする

#7
DRY原則というやつですね。
最初からこれを意識しすぎるのは良くありませんが、必要な場面では使うべきでしょう。
私は、定数については変数名の最初に!などの記号を入れることで区別しています。

私は接頭辞として
ローカル変数にはアンダーバー「_」を付けたり
定数には「C」を付けたり
しています。

では、ローカル変数、スプライト変数、定数、型なんかを書くとわかりやすそうですね。
型についてはScratchでは逆に「angle型」や、「bignum型(文字列での大きな数値表現)」や、「array型(文字列として多次元配列などを表現)」などを行うことで、もっと使い勝手良くなりそうです。

では、基本的な書き方としては、
スプライトごとの変数か→「_」
関数内のローカル変数の区分け→「.」(最近は「/」のほうが見えやすかったり？とか思ってる。)
定数か→「#」(アルファベットにすると一部の場所に定数が固まりすぎるかな。。)
型→基本3文字。
これらをみて考えると、

(_update/ #dbl distance)
(_encrypt/ !int ret cipher)

みたいな感じでしょうか。
Scratchの変数のいい所は「空白」や「記号」なんかをたくさん使えるところだと思うので、見やすくなるように積極的に使っていけるといいと思います。

最近プログラムを読んでいて、スプライトを分けることの重要さが分かって来た気がします。(おそらく馬鹿の山)
なので、備忘録とかの意味も込めて書きます。
イメージとしては「クラス」のようなものかなと考えています。
コスチュームや、定義ブロックの整理も簡単になりますし、プロジェクトを開くときに重くなりづらくなるっていうことですね。

あと、import文としても使いやすいなと感じました。
ただ、そうすると「メッセージ」と「グローバル変数」の活用(どちらも増やしすぎないこと)が大変になってくるので、その「理解しやすい規格」みたいなのが作れたらいいのかなとか。

定義ブロックで分けることもプログラムが見やすくなると思います。

何度も出てくるプログラムではなくても名前を付けた定義ブロックにプログラムを入れることでこのプログラムがどのような意味を持っているのかがすぐにわかると思います。

説明下手ですいません

スクリプトの素材とかだと、定義ブロックで分けていることが多いですね。
「ここの定義ブロックを使えば大丈夫ですよー」みたいな感じ。

The_Infinitys wrote:

私は定数は全て大文字にしたスネークケース、関数(定義ブロック)はキャメルケース、変数は小文字のスネークケース or ケバブケース…
と言うように命名規則を統一するように心がけています(但し癖で関数がスネークケースになる事がある)。あとは無駄なブロックは極力省くようにもしています。

無駄というのが例えばどういったものを言うのか気になりました。まさかコードゴルフをやろうということではないでしょうし。
それを教えてくれればわかりやすいプログラムの書き方を押さえることができる気もします。

Scratchのプログラミングでは、定義ブロックを作ると、「引数の部分に何を入れればいいんだっけ、定義元まで戻って探すの面倒だな……」となりがちだと思います。1ヶ月もさわっていないプロジェクトはたくさんあるでしょうが、それの中を見ると大体そういった状況に陥ります。
そこで、大体3つの方法を考えてみました。他にも「こんな方法も有用だよ～」みたいなのがあればどんどん教えて下さいね！

1. エディターの機能で引数の初期値で説明
この方法は一部のプロジェクトで行われています。定義ブロックを取り出す時に初期値として引数に値が書かれています。
これは面倒なJSONハックを行うことで実現できます。「argumentdefaults」を変更すると上手くいくはずです。

2. 定義ブロックの命名を工夫する
上の方法は少し面倒なので、もう少し簡単な方法を伝えます。

定義 セリフを言う(セリフ) (声)

のようにするのではなく、

定義 (セリフ) を(声)の声で言う

のようにすれば、一目で定義の内容がわかります。ただし、これは横幅を取るなどの問題点があります。

3. ドキュメントを書く
これは、一番面倒な方法です。メモなんかに定義の説明を書くことでわかりやすく説明します。
大きなメリットとして、ドキュメントを書いたひとのプログラミングスキルを大きく向上させると思います。コードの意味のアウトプットを行うことでそのコードに対する理解を深めれます。
また、使う定義(ライブラリなどでは特に)のみにドキュメントを書くのも手だと思います。
書いたドキュメントを隣のタブなんかにおいておくと、「引数の部分に何を入れればいいんだっけ、定義元まで戻って探すの面倒だな……」をctrl + なんかで対処できますね。

ここの使い方として正しいかは分かりませんがメモ兼情報共有として。
何度も使う変数名を順番を早めるためにとりあえずアンダーバーをつける事があると思います。
逆に最後にしたい場合は何が良いのかという思い付きのような話なのですが、検索したところ良い記事を見つけました。「囗」という文字が形も良く文字コード的にも割と遅いようです。
https://rcmdnk.com/blog/2020/08/02/computer-google/