2018年12月30日

空行の後は説明変数を積極的に使うこと - リーダブル コード(57)

今回紹介する方針も非常に重要です。 プログラムのコードが文書であり、自然言語(英語や日本語)よりも厳密に表現できるという主張を通すときに、副作用の問題をなくすために必要な方針です。

初心者や自称熟練者が書くプログラムのコードは、英文というよりは略語からなる文であるために読めないことが多いです。 また、動詞に勝手な意味を付けてしまって後で読めないことも多くあります。 このような略語や専門用語は自分やチームメンバーが理解できるので問題ないと判断してしまいますが、それ以外の人はたとえ熟練者であっても理解できなくなります。 それでは問題です。

だからといって、すべての変数名を分かりやすい英語で書いたとしてもくどい文章に見えてしまうでしょう。 ときには略語や専門用語のほうが適切な場合もあります。

ではどうすればいいかというと、変数名を分かりやすい英語にするケースと、略語や専門用語にするケースであるかを見極めて使い分けることです。 変数名を分かりやすくn文字以上で書くというコーディング ルールや、31文字以内で書くというコーディング ルールのどちらも、片方だけの効果しか考えておらず、そのルールによって副作用を生むのです。 では、どのように見極めるのでしょうか。

それは、前回(リーダブル コード(56))で説明した、「読ませたい文(コード)」については、説明変数を使って、英文として読めるようにすることです。 読ませたい文が関数呼び出しの場合、関数の引数に積極的に説明変数を参照させるのです。

次のコード(Code1)は、どのような処理をしているか読めるでしょうか。

SetReadOnlyAttribute( master_file_path, true ); // Code1


マスターファイルに読み取り専用属性を設定していると読めますね。

では次のコード(Code2)は、どのような処理をしているか読めるでしょうか。

SetReadOnlyAttribute( ReplaceRootPath( path, work, master ), true ); // Code2


何かのパスのルートをワークからマスターに変えて、そのパスの読み取り専用属性を設定していると読めますね。 ちょっとふわっとした理解になりました。

Code2 を書いた人なら、work が書いてあるから path がワーク ファイルのパスであり、その path からマスターファイルのパスに変えて、マスターファイルを読み取り専用属性を設定すると理解できるでしょう。 しかし、他の人には、マスターのフォルダーには、おそらくマスターファイルが入っているのだろうと推測して、それが正しいなら、マスターファイルに読み取り専用属性を設定しているのだろうという条件付きの理解になります。 これがふわっとしていると感じる原因です。

Code2 は 1行だけで、マスターファイルのパスに変える方法についても書かれているので効率的だと主張するかもしれませんが、その情報は初めて読むときには重要ではありません。 後述のようにコードを読む目的によっては不要な情報である可能性もあります。

では、パスを変える方法が必要な情報であるとして、Code2 と同じ処理になるように Code1 を変えてみましょう(Code1B)。

1: master_file_path = ReplaceRootPath( path, work, master );
2:
3: SetReadOnlyAttribute( master_file_path, true );


1行目に、master_file_path と path があることに少し違和感があることに気づくを思います。そこで、その違和感を取り除きましょう(Code1C)。

1: master_file_path = ReplaceRootPath( work_file_path,
2:   work_folder_path, master_folder_path );
3:
4: SetReadOnlyAttribute( master_file_path, true );


前回(リーダブル コード(56))で説明したように、読ませたい文の前の行、3行目は空行にしています。 つまりこのコードを読むときは、まず 4行目を読み、もし、master_file_path の詳細を知りたいなら検索します(最新のテキスト エディターならクリックしただけで 1行目の master_file_path もハイライト表示されます)。 もし master_file_path の詳細について知る必要がないなら 1行目を読む必要はなくなります。

一般的な読みやすい文書と同様に概要から詳細へという情報の階層化が実現されていますね。

1行目の右辺については、説明変数を積極的には使わなくてもいいでしょう。 略語や専門用語を使ってもよい可能性が少し高いです。 なぜなら、左辺の説明変数があることで少し推測しやすくなっているからです。 たとえば、Code1B は、説明不足ではありますが、master_file_path という説明変数があるために、少し推測しやすくなっています。 ただし、同じ単語の変数が多くならない限り、推測しやすくならないことや、略語や専門用語を定義するメリットはないので、基本的には説明変数を使いましょう。

説明変数とは。分かりやすい英語にした名前の変数です。 数学では変数を a, b, x のように1文字や数文字で表し、その内容は、代入文も = の右側で説明していますが、 = の右側だけでなく左側でも説明しています。 説明変数があることで、左辺と右辺に整合性が取れているか、もしくは、取れていないかを判断しやすく、デバッグがしやすくなります。 数学の式は、多くの学者が検証済みですから、整合性の問題を考慮しなくてもいいという違いがあります。

sage_p at 23:15│Comments(0) プログラミング 

この記事にコメントする

名前:
URL:
  情報を記憶: 評価: 顔