プロダクトコードを書けるエンジニアになろう

ソフトウェアエンジニアとして活動していると時折聞く プロダクトコード ですが、最近AIの生成するコードや教育関連と考え直すきっかけがあったので、エンジニア初心者向けにプロダクトコードを書くために必要な要素をまとめてみた。

そもそもプロダクトコードって何？

これは明確に何か辞書的な定義はありません。
ソフトウェアエンジニア界隈では以下の2つの派閥があります。

1. 現時点だけではなく可読性や拡張性などを担保し、商品となるソフトウェアを継続的に開発しやすくしたソースコードを指した呼称
2. ソフトウェア製品のもととなるソースコードだけでなく、自動テストなどソフトウェアの品質を担保するためのソースコードを含めた呼称

ここでは1の意味のプロダクトコードを指して以下を記載していきます。

なぜプロダクトコードである必要があるのか

おおよその場合、仕事で作成されるソースコードは「作成する時間」より「読む時間」の方が長いです。
そしてこの「読む時間」を費やすのは作成者以外の時間です。
チーム全体の生産性を上げるためにも可読性、拡張性の高いプロダクトコードである必要があります。

AIでソースコードを書く時代、それって気にすること？

残念ながら現状、AIで生成されるソースコードはそのまま利用できるほど高品質なソースコードは出力できません。
また、ソースコードの解析についてもソースコードが複雑になればなるほど、ハルシネーションが発生します。
むしろAIに十分に力を発揮してもらうためにこそ、プロダクトコードである状態を保ち、可読性、拡張性が担保されている状態に保つ必要があります。

プロダクトコードってどうやったら書けるようになるのか

知識面で言えば以下のような名著があるので読むことをおすすめします。

• 達人プログラマー
• リーダブルコード

とても読みやすくまとまって現在にも通じる普遍的な知識が記載してあります。
ただ、初心者に知識だけをインプットしてもなかなか実践に移すのは難しいです。
それと参加しているチームやプロダクトによって、何から手をつけたらいいかわからなくなるとおもいます。
なので、手を出しやすいいくつかの簡単なテクニックを記載していきます。

大体どのプログラミング言語でも普遍的に使用できるテクニック

具体的には以下の点に気をつけると良いでしょう。
ただ、上述した通りプロダクトコードはあくまでチームにとって最適化されるものです。
チームに適していないと判断したことを無理に押し通さないようにしましょう。

名前に気をつけよう

以下の点に気をつけると良いです。

• 名前をつける際には可能な限り役割を名称にしましょう
  • OK: user_input, source_hostname など何に利用するかが明示されている
  • NG: data, info など何にでも当てはまるような名称を使用する
  • NG: number, str, file など変数内に格納するデータの形式を変数名にする
• 省略形を使用しないようにしましょう
  • すべての省略形が悪ではありませんが、省略形は以下の様に派閥ができやすく、コードの可読性を悪化させます
    • temporary : tmp, temp
    • receive: rcv, recv

コメントは理由を書こう

コメントはソースコードの情報量を増やすために記載します。そのため、その処理を何故する必要があるかをコメントに記載しましょう。

例えばファイルを1行ずつ読み込んで処理する様なプログラムがあったとします。
そこに必要なのは「ファイルを一行読む」「一行をキー、値に分割する」といった内容ではなく、「省メモリに操作を行うため、一行ずつ処理を行う処理を採用」といったソースコードからは読み取れないバックグラウンドを記載しましょう。

長い処理のまとめのためにコメントを書くような場合もありますが、それらの場合、テストなどを考えると関数として分割した方が高効率です。

よくある問題で「可読性が悪いのでコメントを増やしてください」などの指摘をすると、ソースコードを翻訳したように「A+=B」の処理の上に「AにBを加算する」といったコメントを追加しても情報量は増えないので誰も嬉しくはありません。

関数の役割をはっきりさせよう

関数には大きく分けて2つの役割があります。

1. 処理の流れを制御する
2. 実務を行う

この役割を一つの関数で同時に行わないようにしましょう。
これを行うと関数の役割が複雑化し、実際にやっていること以上にソースコードが複雑化します。

明文化しよう

偏見を恐れずいうと日本のエンジニアはとてもこれが苦手です。
なので、徹底的に明文化しましょう。
特に近年ではCopilotなどの生成AIによるコーディングもどんどん普及しています。
これらと強調するためにも明文化は必要になってきます。

ただ、暗黙知を明文化していくのはとても大変です。
なのでレビューで指摘を受けたところを .github/copilot-instructions.md などに都度追加して徐々に明文化していくのが良いでしょう

最後に

総括になりますが、プロダクトコードとそうでないものの決定的な差は「チームで開発することを前提とするか」です。
上記の内容は守らなくてもプロダクトコードは書けますが、チームの合意形成無しにはプロダクトコードは書けません。
俺の考えた最強のプロダクトコードではなく、俺達の考えた最強のプロダクトコードを書けるようにコミュニケーションと継承を欠かさないようにしましょう。