第三者に意味が伝わるコードを書こう

仕事で改修しているPHPのバッチに、こんな1行が書かれていました。

$sort = 1;

このバッチは、データのソートの元となる値を生成する処理を行っています。デフォルトで$sortに1を代入しておき、後の処理で特定の条件によって$sortを別の値に上書きする処理が書かれています。今回の改修内容は、この$sortを0で上書きするパターンを追加することでした。

でも、罠がありました。

$sortは別のバッチでも値の生成を行っており、別バッチではイレギュラーパターンで0を代入する処理が書かれていました。今回改修するバッチは、その別バッチより、必ず上位に表示させるソートの値を生成しなくてはいけなかったのです。かつ、最終的に連携されるDBの型定義により、ソートの値は整数で無ければいけません。 つまり、$sortには1以上の整数をいれる必要があります。

ということが、資料を漁っていく中で分かったのですが、そんな裏事情なんてこのコード1行だけで察することは難しいです。というか、無理です。危うく不具合を引き起こすところでした。

そういった事情があるのであれば、コメントで説明を入れておいてくれたらよかったのになあと。「1以上の整数じゃないとダメだよ」という1行だけのコメントでもよかった。それだけで、プログラムを改修するエンジニアは、意味があって1という数字を入れているということが分かるし、不具合を回避することができるのではと思います。

設計書なり、ドキュメントなりに仕様を残しておくことも、大切だとは思うのですが、エンジニアが必ず見るものってコードだと思うんです。なので大事なことはプログラム内のコメントに書いておいたほうがいいと思うし、自分もそうするように心がけています。それでちょっとかっこ悪いコードになったっていいのです。

ちなみに以前、コメントだけで数十行書かれているプログラムを見たことがあります。ページを送っても送ってもコメントが続いていました。そこまで長いと、もうコメントが頭に入ってこなくてコードの処理を読もうと思ってしまいました。長い説明は苦手でして…。

簡潔に、分かりやすく、コメントを書くこと。自分でも意識してコードを書いていこうと思います。