カテゴリー
読みやすいコード

名前に情報を追加する/Attaching Extra Information to a Name

名前に追加情報を添付する

前述したように、変数の名前は小さなコメントのようなものです。 余地はあまりないとはいえ、変数が表示されるたびに名前に絞り込まれた追加情報が表示されます。

したがって、読者が知っていなければならない変数について非常に重要なことがあれば、名前に追加の「単語」を付ける価値があります。

たとえば、16進文字列を含む変数があるとします。

string id; // Example: "af84ef845cd8"

読み手がIDの形式を覚えておくことが重要な場合は、代わりにhex_idという名前を付けるとよいでしょう。

単位つきの値

変数が測定値(時間やバイト数など)である場合は、変数名に単位をエンコードすると便利です。

たとえば、Webページの読み込み時間を測定するJavaScriptコードを次に示します。

var start = (new Date()).getTime(); // top of the page
…
var elapsed = (new Date()).getTime() - start; // bottom of the page 
document.writeln("Load time was: " + elapsed + " seconds");

明らかにこのコードでは間違ったことはありませんが、getTime()は秒単位ではなくミリ秒単位で返されるため、機能しません。
変数に_msを追加することで、すべてを明示的にすることができます:

var start_ms = (new Date()).getTime(); // top of the page
…
var elapsed_ms = (new Date()).getTime() - start_ms; // bottom of the page 
document.writeln("Load time was: " + elapsed_ms / 1000 + " seconds");

時間のほかに、プログラミングには他にも多くの単位があります。 単位なしの関数のパラメータとその単位を含むより良いバージョンのテーブルを以下に示します:

Function parameter Renaming parameter to encode units
Start(int delay) delay → delay_secs
CreateCache(int size) size → size_mb
ThrottleDownload(float limit) limit → max_kbps
Rotate(float angle) angle → degrees_cw

他の重要な属性のエンコーディング

余分な情報を名前に付けるこの手法は、単位のある値に限定されません。変数について何か危険なことや驚くべきことがあればいつでも実行してください。

たとえば、多くのセキュリティ悪用は、プログラムが受け取るデータの一部がまだ安全な状態になっていないことを認識していないことが原因です。

そのためには、untrustedUrlやunsafeMessageBodyのような変数名を使用することができます。

安全でない入力を浄化する関数を呼び出した後の結果変数は、trustedUrlまたはsafeMessageBodyです。

次の表は、追加情報を名前にエンコードする必要がある場合の追加の例を示しています。

Situation / Variable name / Better name
A password is in “plaintext” and should be encrypted before further processing / password / plaintext_password
A user-provided comment that needs escaping before being displayed / comment / unescaped_comment
Bytes of html have been converted to UTF-8 / html / html_utf8
Incoming data has been “url encoded” / data / data_urlenc

プログラム内のすべての変数にunescaped_やutf8などの属性を使用しないでください。

特に重要なのは、セキュリティバグのように、誰かが変数とは何かを間違えた場合、特に結果が悲惨な場合に、バグが簡単に侵入できる場所です。

基本的に、理解することが重要な場合は、名前に入れてください。

これはハンガリアン記法ですか?

ハンガリアン記法は、マイクロソフトの内部で広く使用されている命名システムです。

すべての変数の "型"を名前の接頭辞にエンコードします。 ここではいくつかの例を示します。

Name / Meaning
pLast / A pointer (p) to the last element in some data structure
pszBuffer / A pointer (p) to a zero-terminated (z) string (s) buffer
cch / A count (c) of characters (ch)
mpcopx/ A map (m) from a pointer to a color (pco) to a pointer to an x-axis length (px)

これは確かに「名前に属性を付ける」例です。しかし、それは特定の一連の属性をエンコードすることに焦点を当てた、より形式的で厳密なシステムです。

このセクションで主張しているのは、より広範でより非公式なシステムです。変数の重要な属性を特定し、必要な場合には読みやすいようにコード化します。

参考文献:

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック

The Art of Readable Code: Simple and Practical Techniques for Writing Better Code (English Edition)

The Art of Readable Code: Simple and Practical Techniques for Writing Better Code Kindle (English Edition)

「名前に情報を追加する/Attaching Extra Information to a Name」への1件の返信

コメントを残す

メールアドレスが公開されることはありません。