前置き
自分が書いたコードが読めに、読めないのですが！
はぁ＾〜、困りましたねぇ。非常に困りました。どう困ったって、そりゃあもう大変ですよ。なんてったって、自分が書いたはずのコードなのに読めないってんですからね。どうしようもねぇですよ。仕事になんねぇです。なぁ〜にがいけなかったんでしょうかねぇ〜(有名ユゥチュウバァ風に)
ワシくらい腐ったエンジニアになると、こういうことが稀によくある(日本語崩壊)。見受けられるケースとしては、issue1を消化してissue2に移った後、issue1に関連する新たなissue3が切られた時。当該部分を書いたのは間違いなくワシだし、昔と言ってもマージしたのは高々1週間前の話である。…が、issue3に取り掛かるべく自分のコードを読み返して、ふと思うのである。
「あれ！？これってどういう意味なんだっけ…なぜこの書き方なんだっけ…」
別に自己に語りかけて宗教的な気分に浸りたいわけではないのだが、どうにもこうにも哲学的な思考(?)を始めてしまうのだ。未熟なエンジニアにとっては割とよくあるシーンな気がするが、その哲学的な思考(??)をしている時間は当然ながらコードを書いてるわけでもなければ設計しているわけでもない。つまり、何も生み出していないのだ。これは給料を払う側の会社からするとクソほど無駄な時間でしかない。だって生産性がストロングゼロなんだもん(アル中)。会社が社員に求めるのはバリューを発揮すること。何も生み出さない無の境地に至りたいなら出家でもして、どうぞ(提案)
というわけでのっけから辛辣展開でおじさんだいぶダウナー気味なわけだが、ここはひとつ気を取り直し、ワシ含めエンジニア初級者が陥りがちなこの「昔自分が書いたコード読めない現象」を分析、改善策を探すことにしよう。ちなみに、ワシがそうだから無能エンジニア目線で書いてはいるが、何もコードに限った話ではなくいろんな仕事、作業、活動に言えることだと(勝手に)考えている。
「昔自分が書いたコード読めない現象」は何故起こるか
触れているときが、一番わかる
ワシ、ますみん！多分人間！(折部やすな風に)
人間というのは得てして、「ある物事に触れている、熱中している」ときが、一番「その物事に詳しい」ものである。現在進行形で関わっているものについては、例えなんとなくであったとしても「これをして、次にあれをして、そのあとこれをこうして…」と物事の概要を脳みその中で把握できるはず。多分人間なわけだから、ワシにもこれはもちろん当てはまる。
コードを書くにしても、手を動かすことと思考がリンクしているから「このロジックに沿ってるから、この部分をこうしたら動く」みたいな判断は頭のなかで出来るわけだ。そんでコードに落とす。完成。issue終わり。めでたしめでたし。…ホントにめでたいのか？(流れ的にめでたくないに決まってる)
触れてなきゃ、わかんないよ…(メンヘラ)
や〜今回のissueもキツかったっすねぇ！この辺にぃ、旨いラーメン屋の屋台来てるらしいっすよ！じゃけん夜行きましょうね〜(勧誘)
…と思ったのもつかの間。追加要件が入り、前回のissueで変更した部分を掘り起こす(♂)ことになった。前回自分が書いた部分だし内容はアタマに入って…あれ？…内容がよくわかんねぇです？
先程「人間というのは得てして、『ある物事に触れている、熱中している』ときが、一番『その物事に詳しい』ものである」と書いた。これには裏がある。「人間というのは得てして、『ある物事に触れていない』ときは、大概『その物事についてはよく分からん』ものである」ということである。触れなきゃぬくもり伝わんないよ…！(メンヘラ彼女)
人間の脳みそが物事を忘れるのは早く、1日経つと7割忘れると言われている。さらに1日経つと、残った3割のうちまた7割忘れる。1週間も経ったら単純計算で0.3 ^ 7 * 100 = 0.022(%)しかその出来事を覚えていないわけだ。もはや初見レベル。初めましての方は初めまして(動画でよく見る挨拶)。
コードを書いてたときは思考が伴っていたから、そりゃあ書けるし読める。でも「このロジックに沿ってるから」って部分は頭のなかで考えていただけで、実際のコードには落としていない(if文レベルで見ると落としてるといえるかもだけど)。後から見返した時、そのロジックの部分はコードからだと読み取れない(書いてないんだから当たり前)。たとえ1日しか間が空いていないとしても、ロジックなんてもう3割しか覚えてないんだからそりゃあ意味分からんに決まってる。
ここまでくるともう分かったも同然だが、「昔自分が書いたコード読めない現象」が起きる理由。それは思考まで含めてアウトプットなのに、コードには思考の跡が残ってないからである。脳内にあったはずのロジック、昨日は覚えていた仕様。コードからだと読み取れないけど、コードを読む際の前提として必要な部分。それを忘れた時に、取り返せなくなっているからそのコードは読めないのだ。
「昔自分が書いたコード読めない現象」を引き起こさないために
思考の跡を残そう！
理由も分析できたところで、改善策について考えよう。そもそも「思考の跡が残ってない」のが問題なのだから、単純な話をすれば「思考の跡を残せばいい」のだ。手法はいくらでもある。例えば、
- ソースコードになぜその書き方でなければいけないのかコメントとして書いておく
- Githubのissueにロジックを書いておく
とかとか。自分が見返せるのであれば紙のメモでも良いが、コードと一緒に思考を管理した方が楽な気がする。他の人に見せるときでも「こ↑こ↓見て」で済むしね。
コードにしろ文章にしろ、とんでもないバカが後から振り返って見て分かるかどうかを基準に書く
思考の跡を残せばいいのは分かった。あとはどう残しておくかの話。ここでの「とんでもないバカ」は、泣く子も黙るガチモンの大馬鹿野郎を指すとともに「明日以降の自分」も指していることに注意しよう。さっきも書いたけど、明日には7割忘れる無能だからね、仕方ないね♂
思考を残す際に大事なのは、「その書き方で本当に伝わるか？」と考えることだ。なにせ相手は無知蒙昧の大馬鹿野郎。並大抵の文章じゃ理解なんざしてくれない。仕様なりロジックなりを伝えたいと思ったら、それらを丁寧すぎるくらい丁寧に書く。残念だけど、馬鹿に付ける薬は今のところこれしか存在しない。丁寧の基準はズバリ、「明日7割忘れてる状態の自分でも理解できる」かどうかだ。
以下は、デイリースクラムで「今日思ったこと」の欄に「コードにしろ文章にしろ、とんでもないバカが後から振り返って見て分かるかどうかを基準に書く」とワシが書いたのに対して、エンジニアの上司がくれたアドバイスそのまま。
これは基本的に第三者に対して全てそうであることが多い。
自分が発信している情報を相手が理解する割合は想像よりもずっと低い(いいとこ3割とか)
なので、まったく前後のコンテキストを理解していない人(中学生とかのレベル）に説明するつもり位でも情報量としてはちょうどいいくらい
基本的に「ああ、この粒度で読んで理解できないならまあしょうがないな」というレベルで情報伝達をするべき
そのための伝達テクニックとして、`結論から話す`とか`箇条書きにして伝える`とか小手先のものが存在する
なるほど。明日の自分だけじゃなくて、第三者にもやっぱり3割しか伝わらないわけだ。壊れるほど愛する前から3分の1も伝わらないのは明白やったんや(発見 )どんだけ理解力のある人が見たとて3割なわけだから、少なくとも情報量としては今の自分が必要としているものの10/3倍は必要だ。すこぶる大変やなって…(驚愕)
でも最初にちょっと時間を割いて思考プロセスを残しておけば、後々振り返ったときの再現スピードは格段に速くなる。書く手間に比べて後々の得られる利益は圧倒的に大きい。
だから、「issue終わった〜じゃけん夜行きましょうね〜(素)」はそうだけど、「ちょっと待って。この書き方を選んだ理由書いておかんとアカンのとちゃう？(疑問)」からの「じゃあラーメン屋行く前に、明日の自分が分かるように思考をまとめてあげちゃえばいいわけだ(大泉洋)」も忘れないようにしよう(訓戒)
ま と め
「昔自分が書いたコード読めない現象」は「思考まで含めてアウトプットなのに、コードに思考の跡が残ってない」から起こる。
だから「思考の跡を残せばいい」のだが、その際気をつけるべきは「コードにしろ文章にしろ、とんでもないバカが後から振り返って見て分かるかどうかを基準に書く」ということ。具体的には、「明日7割忘れてる状態の自分でも理解できる」くらいに丁寧に書くようにする。
無能エンジニアはこういうところに気を配ることで、少しずつ有能エンジニアに近づくんやなって(しみじみ)
エンジニアの上司からは
つまり、今そこに気づいたということは、
やっと普通に話せるようになった(なる可能性が出てきた)ということで
今までは、自分の発言 ✕ 3割しか伝わっていなかったと思うと
少しは納得感がでてくる
とありがたいお言葉を賜りました。日本語が通じないことで有名な無能エンジニアことますみんです、これからもご贔屓に(臨終)