自分なりの判断基準を整理したものです。
TL;DR
- 「略語は必ず使ってはならない」と絶対的に言えるほど否定するものでもないので、チームで使い方を整理するのがベスト
- その際に考えるべきことは以下
- 狭い範囲でしか通じない略語は避けるべきだが、広く一般で使われている略語は問題ない
- ただし略語が全プログラマには通じるとは限らないので気をつける
- 一般的に使われる略語でも、コンテキストによっては誤読する略語になりうるのでその場合は利用を避ける
リーダブルコード曰く
リーダブルコードには以下のような文章がある。
ぼくたちの経験からすると、プロジェクト固有の省略形はダメだ。新しくプロジェクトに参加した人は、暗号みたいに見えて怖いと思うだろう。しばらくすると、それを書いた人ですら暗号みたいで怖いと思うようになる。 新しいチームメイトはその名前の意味を理解できるだろうか？ 理解できるなら問題ない。 プログラマは、evaluationの代わりにevalを使う。documentの代わりにdocを使う。stringの代わりにstrを使う。だから、新しいチームメイトもFormatStr()の意味は理解できる。 - リーダブルコード 2章 名前に情報を埋め込む 頭文字と省略形
このように「プロジェクト固有の略語は避けるべき」ということと「一般的に知れ渡っている略語なら良い」ということが書かれている。
一般的に知れ渡っている略語
リーダブルコードでは「プログラマは、evaluationの代わりにevalを使う。documentの代わりにdocを使う。stringの代わりにstrを使う。だから、新しいチームメイトもFormatStr()の意味は理解できる。」とありその中で「プログラマは」かなり大きめの主語で書かれているが、ここではプログラマがドキュメントを読む上で読み違えのないような略語を指すと思われる。例えばある程度の量のドキュメントやソースコードに接してきたプログラマは str を stranger とは誤読しないし、 var を variety と勘違いすることは少ないと思われる。
ただ、「conn は connection だ」のような言葉のマッピングは経験値で培われるもので、網羅的な情報があるわけでもなく、コンテキストによっては全く知る機会がないこともあるので、前提として「知らない人がいるかもしれない」という心持ちでコードレビューなどには望んだほうが良いと思われる。
略語と誤読
一般的な略語であれば問題ないかと思われるが、例外として一般的な略語でも誤読が誘発されるものは避けるべきだと考える。
例えばプログラムの処理内容として「バラエティー番組の種類を選択させたい」というような内容を記述するときに variety と variation という単語が登場する。そのときに一時的な変数名などに var を使うと、コードの作り方によっては「もしかしてバラエティー番組のことを指しているのか？」といらぬ懸念を抱かせてしまうので、このような状況下においては略語を避けて正しい言葉を当て込むほうがよいケースもあると思われる。
絶対的な線引はつくりにくい
前提が「一般的に知れ渡っているものなら略語でも大丈夫」としたいところだが、誤読を誘発するようなものなら避けるべきなので、何も考えない方向にいくなら「略語は原則使わない」だがそれも窮屈すぎる場面があると思われる。
そのため、やはりどの程度で抑えるかはそのコードに関わる人たちの認識次第なので、リーダブルコードの一節を起点に認識合わせをしてチームとしてどうあるべきかの方向性を話をすると良いのだと思います。
