[[📒Productivityを上げるために大切な100のこと]] No99. 🥈 ---- 皆さんは自分の名前を間違えられたことはあるだろうか。私は数えきれないほどある。漢字の違いはそこまで気にしないが、かすりもしない名前で呼ばれると、本人に悪気があろうとなかろうといい気分はしないものだ。それはほとんどの人が同じだろう。 ## なぜか名前が重要視されない世界 私の本職はエンジニアだ。なのでプログラミングやドキュメントというものを山ほど書いてきた。これからも書くだろう。そしてその何倍にも渡る数のそれらを読みもするはずだ。 ところが、プログラミングやドキュメントの話になると、人の名前とは違い、途端に名前の扱いが雑になるケースを何度も見てきた。いくつかパターンを示そう。 ## 何がしたいのか分からないケース 以下は`check`という名前の関数だ。 ```ts function check(x: string, y: string) -> boolean { // 中略 } ``` `boolean`を返却することから何かをチェックして OK or NG を判定することは分かる。しかしそれ以上の情報がない。この場合、==利用者は結局実装をすべて確認しなければならない==。せっかく具体的な処理をインターフェースで抽象化したのに、なんともったいないことか。 ## 嘘をついているケース 何がしたいのか分からないのはまだいい方だ。一番最悪なのは、==インターフェースと実際の処理が乖離すること、すなわち嘘をついているケース==だ。 ```ts function add(x: number, y: number) -> number { // 中略 } ``` このコードを見た人に`add(10, 20)`の結果を聞けば、ほぼ全員が30と答えるだろう。しかし現実は甘くない。このコードは`1020`を返す。つまり結合した結果を返却するのだ。そのような関数の存在はアリだが、それに`add`とつけるのは適切でないだろう。`join`であれば誤解をしなかったかもしれない。 ## 仕様書と手順書の混同 データを管理する仕事があったとき、仕様書は**データの仕様(ルール)を示す**もの。手順書は**データを使う手順を記載する**ものだ。だが実際にはこれらが混同するケースは多い。特に仕様書がないものに関して顕著だ。 現場では仕様よりも手順が大事なことが多い。そうすると、==手順書の中に仕様が記載されること==になる。『この作業をするときのこのデータはこういう意味だよ』というのを伝えるためだ。その後は仕様書のページに以下の一文が加わる。 ``` 仕様は『手順書』をご覧ください ``` 正直なところ、仕様書と手順書の切り分けは難しいことが多々ある。手順をベースに後付けされた仕様書は実質手順と一心同体だ。そのデータを既にある手順以外で使うケースが考えられていない。すると、仕様と手順は何が違うのか...? 同じであれば別にする意味はないのではないか...と考えるわけだ。 同様のことは**ツールのマニュアルと手順書**においても発生しやすい。この辺は[[PKM]]を学んでみるのがいいと思う。 ## 揺れる名前 同じ意味をさす言葉が微妙に違った形で表現されることがある。たとえば`マスターデータ`という言葉だ。これは人によって異なる解釈をされるケースがある。 - データ提供元の元データ - DBで管理される参照メインのデータ - リリースで本番更新されるデータ これらの齟齬はいとも簡単に大きな問題を引き起こす。多少嫌がられても、しつこいくらい用語の確認はした方がいい。個人的には[[DDD]]の[[ユビキタス言語]]を定義するのがオススメだ。そのまま開発にも有効活用できる。 ## 大文字や小文字の違い 細かいと思われるかもしれないが、大文字と小文字の違いは重要だ。たとえば[[JavaScript]]は`J`と`S`が大文字で他は小文字だ。大文字と小文字の違いには以下のような理由がある。 - 単語の区切り - 文体のバランス - その他の想い 悪気はないだろうが、これらを正確に記載する人はことのほか少ないと思う。[[JavaScript]]なら例えばこうだ。 - Javascript - javascript - ジャバスクリプト - ジャバスク [[Slack]]とか砕けた場であれば気にする必要はない。ただ、公式に公開される情報であったり、その名前をもつ本人の前では気を付けたほうがいいだろう。可能であれば、名前と同じように相手が使った文面をそのままコピペすることをオススメする。 私も社会人5年目の頃までは配慮が甘く、大文字や小文字の不確かさを当時のスーパーエンジニアの方に指摘されたりもした。正直、『細かいなあ....』という気持ちはあったが、今では非常に納得できる。人の名前に例えると、漢字を間違えたりカタカナで表現することに相当するのだから。 ## 名前と信頼 私が今まで関わってきた人々を見て気づいたことがある。==名前の表現が正確な人は信頼度が高く、読みやすいコードやドキュメントを書く人が多い。逆にそうでない人はその逆だ==。味方にすると心強い人からの信頼を一気に勝ち取るという意味でも、名前には気を付けたほうが長い目で[[プロダクティビティ]]の向上にも繋がるはずだ。 ## 分かりやすい名前 そしてできることなら、誰にでも分かりやすく誤解を生まない名前を付けることにチャレンジしてほしい。ページ名の優れたドキュメンテーションは非常に読みやすく、メンテナンスもしやすい。ソースコードは言わずもがなだ。 最後に、[[📗ドキュメントのキャッシュ戦略を考える]]でも載せた名言を再び引用させてもらおう。 > There are only two hard things in Computer Science, cache invalidation and naming things. (コンピューターサイエンスでで本当に難しいことは2つだけ。キャッシュの無効化とネーミングだ。) 名前などどうでもいい。気にせず作業を進めたいと思うかもしれない。だが思い出してほしい。本来、==名前というのは最も時間をかけて決めるべきことの1つなのだ==。