【Ruby】名前の付け方と読みやすいコードについて

####はじめに
コードを記述するにあたり、初学者でも少し気をつけるだけで効果のありそうなポイントに絞ってまとめてみました。私が自身初学者なので自分の備忘録も兼ねています。情報を文献などで検証していますが、見落としや誤りがありましたらお教えいただけますと幸いです。

命名規則や記述例はRubyのものを用意しています。

#####ー　目次　ー
1.読みやすいコード
2.名前の付け方
3.見た目の整え方
4.コメントを入れる
5.条件分岐
6.参考文献

####1.読みやすいコード
プログラミングの多くの時間はコードを読み、理解することに割かれます。同じ意図が迅速に伝われば伝わるほど、読みやすいコードということができそうです。そのためにどのような工夫が必要なのでしょうか。容易に想像がつきそうなポイントは以下の２点です。

・量が少ない
・わかりやすい

上記の２点は、プログラミングに限らず両立しない場合があります。丁寧に記述された厚い本の方が、スマートに要点を整理した本よりも、苦労せず読めるということは珍しいことではありません。記述量とわかりやすさが競合するような状況では、「どちらが解読するための時間を節約できるか」を考えると、迷うことも少なくなるはずです。

この記事を書くのに参考にしました書籍、『リーダブルコード』p.3より引用したいと思います。

コードは他の人が最短時間で理解できるように書かなければいけない。（中略）「他の人」というのは、自分のコードに見覚えのない６か月後の「君自身」かもしれない。

####2.名前の付け方
変数、メソッド、クラスなど、自分で名前を付ける機会がプログラミングにはとても多くあります。簡単に気をつけることのできそうなポイントを探してみました。

１.単語の省略を勝手に作らないこと

example2_1.rb

#良い例
def add_point
  #名前の通り、得点を加算する処理
end

#悪い例　勝手に略語を作ってしまった場合
def ap
  #以下省略

２.誤解のある名前を避けること

example2_2.rb

def calculate
  #すごく時間のかかる計算処理
end

なにかとてつもなく時間のかかる計算をするメソッドを作ったとします。計算なのでcalculateと名前をつけました。
自分は「とてつもなく時間がかかる」ことを知っているので問題はないのですが、他の人はcalclateが普通意味するところの「簡単な計算処理」だと思って実行してしまうかもしれないので、computeなどの言葉を使うことを検討すると良いかもしれません。

「名前自体が変数やメソッドなどの説明を果たすこと」に気をつければ、上記の問題点は解決できそうです。命名に関する決まりごとについては以下に簡単に記述しています。

名前を付ける際の決まりごと　（Rubyの場合）

	文字	区切り	具体例
クラス	単語の頭は大文字	続けて記述	SampleClass
メソッド	全て小文字	_　を使用	erace_name
定数	全て大文字	_　を使用	MAX_HEIGHT
変数	全て小文字	_　を使用	user_id
ファイル	全て小文字	_　を使用	sample.rb

####3.見た目を整える
適切なインデントを入れることで、見た目を整えることができます。
また、クラスやメソッドの定義と定義の間には空行を入れます。

いつ使うのかわかりませんが、渡された具を元におにぎりを作るメソッドを例にしています。
（「おかかおにぎり」と出力されます）

example3.rb

#改善前
def make_onigiri(nakami)
puts "#{nakami}おにぎり"
end
make_onigiri("おかか")

#改善後
def make_onigiri(nakami)
  puts "#{nakami}おにぎり"
end

make_onigiri("おかか")

####4.コメントを入れる
適切なコメントを記入することによって、コードを読み解く手助けをすることができます。ここでは、不要なコメントと、コメントを減らすにはどうすれば良いかを記していこうと思います。

#####コメントを入れるには？
#を付けることによって、その行をコメントにすることができます。

example4_1.rb

#これはコメントです

#####不適切なコメント

【コメントをしなくても、名前などからわかる】

example4_2.rb

#得点を加算するメソッド
def add_point(point)
  point += 1
  return point
end

【定義がそもそも不適切でコメントが必要】

example4_3.rb

def complex_method
  #コメント例　A条件が偽でないとき、かつ 条件Bか条件C少なくとも一方が真...（複雑なコメント）
  #複雑な処理...
end

メソッドの定義の中へのコメントは避けるべきです。もしコメントがないと理解が難しいほど複雑なメソッドを作ってしまっていたとしたら、内容を整理します。

####5.条件分岐
コードが複雑になりやすい条件分岐で簡単に注意できそうなポイントをまとめてみました。
・条件に否定形を使っている場合、肯定形に直せないか
・三項演算子を使うよりも、複数行のコードの方がわかりやすいのではないか
・if文がネストしている場合、case文で読みやすくできないか

####6.参考文献
Rubyコーディング規約
リーダブルコード より良いコードを書くためのシンプルで実践的なテクニック

####おわりに
初投稿ということもあり読みにくかったかもしれません。
最後まで読んで下さりありがとうございます。