はじめに
Rubyで書いている時のコードの規約の経験まとめとして書いてます。
読み易いコードの定義
読んだ人が変更を加えたりバグを発見することができるようになるレベルで最短でコードを読み終えることができるということを目標にしてコードを書かなければならない
変数もメソッドもクラスも何を司っているのかを直訳した時に分かるようなっていること
表面上の改善として、任意に書けるものへの理解のしやすさを考える
変数、メソッド、クラス、凡そ任意で書き、定義することができるこれらのコードの部分はよく考えて書かないと、前述のコード定義をクリアすることは至難である。正直、こちらが意図して書いていたとしても誤解を招くことすらある。誤読される可能性を出来る限り排除しないと、こっちが何も考えてないように思われるから腹立たしいものです。
明確な単語を使用する
簡単な動詞、名詞、形容詞、前置詞を使用する。
英単語を使用する上で、カチコチの英文法に則って書く必要はなく、むしろそれが混乱させることを招くこともあるので、その辺はプロダクトやチーム内のルールとして納得するような状況判断も必要になってくる。
例えば、of。A of Bの訳詞方は、BのA単体ではなく、AのBと言う使い方も存在する。どちらを使っても問題無いような時でもBのAに慣れ親しんでいる人が多い場合、警告されたりします。
口語表現は、強調の意味で文法を無視するなんてことも多々あることで、海外の人でもここまで気を遣って表現することはないのが事実なんですが、コーディングにおいては海外の契約書書くとかその辺の公式文書を書くくらいのカッチリさが必要みたいですね。
多分、名詞として使われることが有名でも形容詞としても使える単語があったとして、使用すればそれも警告対象になりそう。例えば、product costとか。要は、見慣れてるか見慣れていないかと言うすごい経験的なものに依存しています。
過去分詞も過去形の動詞と混同されるので避けた方がいい。
文章読解における厄介な分詞もまた文脈依存で判断する必要があるので、表現としては避けるべきであろう。およそ文脈判断を要求される文法は使用しない方がいいと思われる。関係代名詞などはこの構文の性質上、流石に長くなる文法なので、使用されることは無いだろう。しかし、それぞれの文法が折り重なった場合の判断する術は数多くあるが、なるべく短く情報を入れ込む必要のある表現を余儀なくされるコーディングにおいて、文脈で委ねる表現はどれも避ける必要があると思われる。
意識すべき文法は多く無い
- 動詞を使用する時は5文型を意識する必要があるので、自動詞と他動詞の使い分けは意識する。
- 複数形と単数系
今のところ、気にするのはこれくらいですね。
自明の言葉は不要
例えば、registered userと言う変数名はuserで良い。DBに入ってきている時点で登録されていることは明白だからである。
汎用的な名前を避け、具体的な名付けを行う
名詞単発で変数を作ると、コードが増えてきた時に読み手の誤解を招くことになる。例えば、あちこちにdataとしかない変数があると、読み辛さを増す。
略記は避ける
これは納得。流石にget_user_dataをgudとかにされたら分からん・・・
メソッドは動詞を使用
処理を行うコードなので、動詞を使うのがベスト。
クラス名や変数は名詞を使用
何を司っているクラスなのか、何が格納されている変数なのかを意識する
言い換え表現は使用しない
コードは文章では無いので、言い換え表現はしない方がいい。なんとなく文章書く感覚でやってるとやっちゃいがち。
Memmber = userなどのように殆ど同じ意味を持つものを使って表現することはせず、同じ意味の持つものは同一の単語で統一する。
非推奨な記法
ハンガリアン記法と呼ばれる型やスコープなどの情報を変数名やクラス名に入れ込む命名法、現在非推奨であり、多くの場合のアンチパターンとなるらしいです。
例えば、配列であれば、arr_dataとかにして変数にするなどは避けるべきである。