フィヨルドブートキャンプ Part 2 Advent Calendar 2022 - Adventar の4日目の記事です。
昨日はmaeda-mさんの Heroku の代替 OSS を試した話 | お日記させていただいてもよろしいでしょうか。 でした。
フィヨルドブートキャンプ | FBC (以下FBC)の提出物のレビューをするときに参考URLに使えそうな資料を自分で書こうシリーズの2年ぶり2回目となります。
って書いていて気づきましたがAdventCalendarが3回目ということは丸二年以上メンターやってるんですね。早いなあ😲
なにこれ？
FBCの提出物をレビューしていて、rubyの最初の方でよく変数名についての指摘をするので、右も左も分からない初心者の方に変数名の大事さ、どういう事を気をつけて欲しいかを説明します。
注意事項
- プログラミング初心者向けの記事です。
- 「初心者に分かりやすい」を最優先でざっくり書くので正確では無かったりしてもご容赦ください 🙏
- 頻出の例を書くので、生徒さんの提出物と同じ例があるかもしれませんが特定の提出物を貶す意図はありません。
前提: 変数名がなぜ大事なのか
- FBCで教えるプログラミングは仕事で使うものなので読みやすいプログラムにする必要があります。仕事で使う文章を分かりやすくすることと同じ。
- その変数に何が入っているか？は変数名で推測できなければ処理の流れを追うしかなくてとても大変。
Rubyの作者の Matz の好きな言葉は 「名前重要」ってぐらい大事なんです。 Rubyist Hotlinks 【第 1 回】 まつもとゆきひろさん
どんな変数名が良いのか
理想を書くと「そのプログラムを読む人全員が中身を推測でき、読みやすく書きやすい簡潔な名前であること」です。
「書きやすい」は自分なのですぐ分かりますが、「読みやすい」は書いているときは分かるので注意しづらいです。 他の人(仕事であれば同僚、レビュワー、未来の自分)が読みやすくなるようにという視点を持つと良いです。
指摘事例
名前と中身が違う
file_content = "/path/file.txt"
↓
file_path = "/path/file.txt"
この例だとfile_contentなのでファイルの中身と思いきやファイルパスが入っているので中身が違うという事です。
最初からすみませんがあんまり良い例では無い気はします 😓
この問題自体は頻出ですが、違い方が幅広くて引用すると具体的になり過ぎてしまうので 🙏
こんな事はしないって思うかもしれませんが、英語の意味を考えるとちょっと違うとか、変数名を同じパターンでつけてたけど一部のデータがちょっと意味が違う…とか気を抜くといつのまにか発生してしまうものです。
表記ゆれ
file_string = read_file('path/file.txt')
formatted_text = format(file_string)
↓
file_string = read_file('path/file.txt')
formatted_string = format(file_string)
ここはstringとtextと同じ意味なのに同じプログラムで複数使ってしまっているということです。
同じプログラムで同じようなものに別の単語を使っているとそこに意図があるものかと考えてしまいます。
例えばstring/textが使い分けられていると、「もしかしてtextを使っているところはstringよりも長い文字列が入っているので区別してるのかな？」と考えてしまったりします。
大規模になると厳しくなってきますが、一つのプログラムでは同じ概念は同じ単語を使うようにしましょう。
抽象的過ぎる単語を使う(info/dataなど)
file_info = read_file_info('path/file.txt')
row_data = count(text)
↓
file_attributes = read_file_attributes('path/file.txt')
row_count = count(text)
ほぼinfo/dataの事ですが、変数は全て情報だしデータなので、大体のパターンはinfo/dataを消しても大差ないです。まずは消してみましょう。
もちろん情報量がゼロでは無いのでfile_infoだと「ファイルの本文以外の情報」が入っているのでinfoをつけたというケースはあって、意味はあります。
その場合はfile_attributes/file_metadataなど(row_dataの方ならrow_count)もっと具体的な単語が使えるので言い替えを考えてみましょう。
省略し過ぎ、慣習に無い省略
ざっくり言うと「省略した方が読みやすく、分かりやすい事もあるが、慣習や事例を色々見ないとうまく省略するのは難しいので初心者のうちは省略しないようにした方が良いよ」という事です。
ここについては以下にいつも使わせてもらっているFBCメンターの @jnchito さんの良いまとめがあるので見て欲しいです。 プログラミング初心者は変数名やメソッド名を略さない方がいいよ、という話 - give IT a try
長過ぎ
file_contents_with_file_attributes_from_arguments
↓
file
まあこれは見ればわかると思います。これが一回ならともかく何度も出てくると読むのも書くのもキツいですね 😓
これはケースによりますが中身と属性情報両方あってfileなので file_contents_with_file_attributes → file、from_argumentsという情報はこの変数を利用するときに重要じゃなければカットするとかですね。
単語を言い替えたり概念をまとめたり比較的重要では無い情報をカットするなどして短くしてみてください。
前項の省略とのバランスが難しいのですが、優先順位として「意味の分からない短い名前」よりは「長過ぎるけど意味は分かる」方が良いので困ったらこちらを妥協した方が良いです。
xxx_list/xxx_array
file_list = [file1, file2]
new_user_array = [User.new, User.new]
↓
files = [file1, file2]
new_users = [User.new, User.new]
これは慣習の問題で、他と比べて具体的になってしまいますが、本当によく見るので掲載。
他言語では違うこともありますが、Ruby(少なくともRails界隈は確実に)配列を表現するときに複数形を使います。
個人的にも_list/_arrayよりも複数形の方がシンプルになるので好きです。(デメリットは複数形が無い単語を避ける必要があるところ)
また、ちょっと高度な話ですが、例えばusersという変数名でUserクラスが存在すればUserクラスのインスタンスの配列である事を期待するという事も覚えておいて欲しいです。
まとめ
事例集なので配列の例ぐらいしか書けませんでしたが、慣習は大事です。「よく見る名前を使ったよく見るパターンのよく見るプログラム」が一番分かりやすいので。
たくさんプログラムを読むのが大事ですが、最初は良いコードが何かわからないと思うので、技術書のサンプルコードを読むときに命名についても意識してもらえば参考になるかなあと思います。
名前付けについてもっと知りたい！という方におすすめは雑誌の一特集ですが、以下の雑誌の特集「名前付け大全」をオススメしています。
リーダブルコードとかの名著で命名に関連するものもありますが、この記事は一時間もあれば読めるのにすごく良くまとまっているのでイチオシです。 有料ですが興味あれば是非。
より良い命名への道は遠いです。
というか10年プログラム書いてても迷う事はよくあるので一緒により良い命名ができるよう精進していきましょう 💪
明日は いっしー さんの 「就職して1ヶ月経過したお気持ち系記事」です。楽しみですね 😄
追記 2022/12/23
前述の名前付け大全の作者の方の発表資料が公開されていたので追記。 記事よりも情報量少ないようですが、コンパクトにまとまってるし無料なのでとりあえずこちらを見ると良いと思います。