2017.12.28 Android iOS Server WEB 技術開発

開発を進めていく上で気をつけるべき事項その2

さてさて、季節はもうすっかり冬ですね。
寒くて毎日凍えている hoge太郎です。
前回の投稿が夏だったので次回も夏かも知れませんが、まぁやっていきましょう。

ドキュメントとソースで異なる名前をつけない
名前は省略しない
速度より可読性を重視する
同じコードを書かない (関数化)
役割を分担する (クラス化)
仕様による制約をコードで表現する (より良いインターフェース設計)
何でも出来る→これしか出来ない
例外処理をちゃんと書く
ログ出力にも設計を
リリース作業は簡単に
環境変数の勧め
まとめ

第2回名前は省略しない

えー、表題の通りです。
私はこの業界にかれこれ10年ほどいるのですが、これまでに幾度となく他人の書いた仕様書らしき物、設計書らしき物、プログラムらしき物を見てきました。
そしてずっとこう思っていました。

なんだよこの暗号は！

お前等は子供の名前も適当に決めるのかと問いたい。小一時間問い詰めたい。
以降、少し長めの愚痴になるので結論だけ知りたい方は読み飛ばしてください。

以下、身近なプロジェクトから抜粋してみた。

Lv1

省略名	正式名称 (と思われるもの)
btn	button
ico	icon
img	image
bg	background

ここらへんはまぁ分かる。

Lv2

省略名	正式名前 (と思われるもの)
cls	class
app	application
info	information
flg	flag
err	error
num	number
del	delete
msg	message
param	parameter
cmd	command
cnt	count

これもまぁ分かる。

Lv3

省略名	正式名称 (と思われるもの)
tb	table
mtb	master table
tms	timestamp
dl	download
succ	success

おやおや・・・？

Lv4

省略名	正式名称 (と思われるもの)
rs	result set
p	parameter
v	value
v	version
nid	???
sh	???

前後の文脈から辛うじで読み取れるレベル。
中には未だに何の略称なのか分からないままの物も・・・

問題点

大体分かるじゃんって思いますか？
もちろんLv1、Lv2くらいまではほぼ1対1で対応する正式名前が分かります。
だからそこまで問題ではないです。
ただ、それでも頭の中でいちいち変換が入る訳です。
これはどれだけ小さかったとしても無駄な負荷ですよね。

この先ずっと見た人が瞬時に何を指しているのか判別出来ると言える程
浸透した一般略称であれば許容は出来ます。
しかしそんな事保証出来ますか？

出来たとしても、そんなあやふやな名前を付ける事が省略しない場合と比べて
どれだけの利があるのでしょうか。
せいぜいあなたの時間が数十分から数時間削減出来る程度じゃないだろうか。
しかしその小さな利を得る代償に、その何倍もの時間イライラする人が生まれるのです。

イライラするって大した事じゃないように思えるかも知れません。
しかし本当に意味の分からない略称はイライラする度合いが大きい上に、
不具合があってロジックを追いかけている時にこれなんだっけ？ってなったり、
機能追加を行う時にそれまでの文化を引き継ごうと訳の分からない名前を
自分も使う事になるのです。
これはちゃんとしようとしている人にとっては苦痛でしかない事です。

パッと見で何を指しているのか読み取れない名前は、
それが何を指しているのかを前後の文脈で推測しなければいけないし、
正しいかどうか不安なまま読み進める事になる訳です。

想像してみてください。
あなたは今ある不具合の調査をしています。
ロジックも複雑です。
何をしているのか必死に頭の中で論理的な文章にしている時に
なんだろうこのvってとか、vってvalueのvなのかっていう
どうでもよい&余計な思考が挟まる訳です。

そしてそういうコードには得てして似たような水準の省略名が沢山あって、
それらにいちいち引っかかる訳です。
もっと言うとコードを読み取る時に弊害となるのは何も省略名だけではありません。
インデントが乱れていたり、スペルミスが混じっていたり、
コメントが正しくなかったり、他にも細かい問題は山ほどあるのです。
エンジニアであれば真剣に思考している最中に割り込みが入る事が
どれだけ生産性に悪影響を与えるのか分かると思います。

まして障害発生などで直ぐに原因を突き止めたい時間のない時の弊害を考えると
気軽に省略していい程どっちでもいい事とは言えないのです。

例えば省略名を使わなければ長過ぎて使えないなど、ある制約に引っかかるのであれば仕方がありません。
もしくは省略名を使う事に明確な意味と利益があるのであればそうするべきです。
しかし手を抜いた結果省略しているのであれば、それはあなたが考えているよりも遥かに重罪だと心得ましょう。

まとめ

プログラミングってV字モデルの下流にあるので細かい部分は疎かにしがちなのかもしれません。
しかしあなたが上流に対して仕様書に抜けがある、表記が揺れている、などの不満を感じるのと同様に、あなたの下流にあたる保守をする人もあなたの些細だと思っている手抜きに対して不満を募らせていくのです。
せめて出来る範囲で気を遣っていきたいじゃないですか。
そういう気持ちを持っていくと自然と名前を無闇に省略しなくなるし、スペルミスも減るし、インデントもちゃんと揃えるようになっていくものです。
それがモノづくりに携わる人としての礼儀であり、持つべき心です。

そもそも名前なんて殆ど省略する必要のないケースばかりです。
省略しない名前を付ける事が難しい訳でもありません。
そんなちょっとした手抜きによって世のエンジニア達が仕事がつまらないと感じてしまったとしたら、こんなに悲しい事はありません。

たかが名前、されど名前。

より良い方法の探求を辞めてしまったらもはやエンジニアとは呼べません。
まずは名前から、手抜きを辞めてみましょう。

未来のエンジニアライフに幸あれ！