1行1行を説明できるソースコードを書こう｜熊本のITエンジニアよしハムコロリの技術メモ

こんにちは。熊本でITエンジニアをしている、よしハムコロリです。

25年以上ITエンジニアとしてやってきて、多くのソースコードを書き、レビューも行ってきました。

今回は、私がソースコードについて思うところをつらつらと書いてみたいと思います。

駆け出しの頃に厳しく注意されたこと

私がSESで客先に行きはじめてから半年くらいのときに、「条件を満たす場合にログを出力する」という対応をしました。
過去に同様の対応があって、私は過去の対応時のソースコードをコピペ(コピー&ペースト)で対応しました。
ソースコードを実装したら、レビューで知見者に見てもらうのですが、そのとき上司から「この処理は何をやっているの？」と質問されたのですが、単純にコピペで対応した私は、その処理の内容を理解しておらず答えることができませんでした。
知見者からは「説明できない処理を組み込んだのか？」とめちゃくちゃ突っ込まれました。その後、上司からも呼び出され、長時間の説教を喰らいました…。

説明できないソースコードは…

ソースコードを書くとき、つい「動けばいい」となってしまうこと、誰しもあります。でも、それだけではダメで、組み込む箇所の前後関係を調べた上で、組み込む内容をちゃんと理解した上で組み込むことが大切です。ものすごく当たり前のことを言っていて、おかしいと思われるかもしれませんが、プログラマーであれば大体皆通る道ではないかと思います。
組み込んだ人が説明できないソースコードは、他の人にとって推測はできるかもしれませんが、真意は分かりません。大抵において説明されず誰も理解していないまま世に出て行ったソースコードは数か月後、皆が忘れた頃くらいに不具合となって帰ってくる傾向があると思います。バグや誤解の温床になる可能性が高い為、実装するソースコードは説明できるようにしましょう。尚、理解した内容に基づき、ソースコードにコメントを残しておくのが理想的ですね。

プロのプログラマーとして

納期が迫っていたりすると焦って、「動けばいい」を優先させてしまうことがあるので、自分への戒めも込めて書いていますが、説明できないソースコードを組み込むことはプロの仕事としては無責任だと思います。先述の私が超叱られた話でも書いていますが、レビューという工程は「内容が適切か」を判断する場である為、合っていようと間違っていようと説明ができなければ、「内容が適切か」の判断をすることができません(まあ、レビューはそういう抜け漏れなどを防止する為にある工程ですからね…)。自分の趣味で作っているソースコードは構いませんが、仕事として組み込むソースコードは責任を持って対処したいですね。

飛ばさず1行1行理解すること

自分が組み込んだソースコードを1行1行理解することは、ものすごく自分の力になります。プログラマーとして成長したいと思う場合には効果的だと思います。私は不器用な人間なので、方法を知らないだけかもしれませんが、私はプログラマーやITエンジニアとして成長していく為には「近道」は無いと思っています。たくさんのソースコードを読み、書き、分からないところを1つ1つつぶしていく。
なが～いソースコードを1行1行理解していくことは大変です。読み飛ばしたくもなります。でも、これも大体において、読み飛ばした場所が後で問題になりますw

溢れかえる情報とハイスペックのAIであっても鵜呑みにしない

最近はインターネットや書籍などに膨大なサンプルコードもありますし、AIがほぼほぼ生成もしてくれます。
でもそれはあくまで「自分以外」が実装したもの。自分のものにする為には1行1行理解が必要と思います。なんなら、AIに毎行の説明をさせてそれを理解するのは1つあるかもしれません。
あと、インターネットの情報でもAIが生成したものでも誤りはあります。有用な情報には変わりありませんが、鵜呑みにしないようにしましょう。

公式リファレンスを見よう

ソースコードを説明するときに標準関数などについても理解が必要になる場合があります。インターネット上にもたくさん情報はありますが、私が最も見た方が良いと思うものは各言語やフレームワークの公式リファレンスです。公式リファレンスは日本語化されていないものも多いですが、それこそAIの力を使うと把握しやすいと思います。公式リファレンスを活用しましょう。

ソースコードは“未来の自分や他人への手紙”

これは結構言われることかもしれませんが、ソースコードの1行1行には自分の思いが詰まっていて、他の人への配慮がされているべきで、そのソースコードが次、読まれるタイミングでとても分かりやすい内容であることは非常に重要なポイントだと思います。極端に言うと、好きな人に手紙を書くような気持ちでソースコードを組み込むといいと思います。

さいごに

最後まで読んでいただきありがとうございました。起承転結もなく、取り留めない内容になりました。私は全く職人気質ではありませんが、苦い経験も数多くしてきているので、この手の話は止まりません。プログラマーの仕事はこの部分に尽きると思いますし、どれだけ他の人が把握しやすいソースコードを書けるかを考えることが醍醐味の一つではないかと思います。感想や質問などがございましたらコメントを書いていただけると嬉しいです。また、この記事が少しでも参考になりましたら、他の方にシェアしていただけると嬉しいです。最後に、当サイトではご寄付を募っております。サイト運営に活用させていただきたいので、もしご賛同いただける場合は、以下のボタンよりご支援を検討していただけると励みになります。