コードをコードで説明するな

学生時代に先生に言われた記憶がある。
その当時はレポートの再提出も重なってたので負の感情も含めて受け止めてたけど、今思うととても重要な言葉だったなぁと感じる。
これによって私のプログラミングのスキルもある程度担保されてるところがあるし、プログラマとして初心者かどうか判別する判断材料としても利用してる。
今になってはそれくらい大事にしてる考え方なので書く。

例えばこのようなプログラムを説明する際に

 user = User.new(email: 'test@example.com')

「emailを'test@example.com'にしてUserをnewしたuserを作っています。」

相手が初心者であればこんなことを言われる場合もある。
ただ、これは説明してるとは言えない。プログラムを音読しているだけという方が正しい。

答えるのなら
「ユーザークラスのインスタンスを作成、メールアドレスには'test@example.com'を代入しuserという変数に代入しています。」
のように返すべきだと思う

これにより何が変わるのか。

まず第一に理解しやすい。
日本語とプログラミング言語を混ぜたルー語のようなものを言われるよりも、全て日本で説明された方が明らかに聞きやすい。

第二に相手の習熟度がわかる。
例えばRubyにおけるUser#newが何をしているのか理解していない人ならば後者の説明が行えない。
簡単に言えば行ってることはインスタンスの作成であることから、理解しやすい処理だと思われるのでオブジェクト指向としての理解度がわかる。
もしもこれ以上の技術力を持っていることがわかっているのなら、もっと深い階層で理解し得ていない部分があるのかとも窺える。

これらの要因からプログラムはちゃんと適した言語で説明すべきだろう。