技術とか戦略とか

証券レガシーシステムを8年いじってから転職した普通の文系SEによるブログ。技術のみではなく趣味の戦略考察についても。

保守性の高いコードを作成するために心がけること

ソースコードは作って終わりではなく、その後何年、何十年にもわたって保守開発が行われます。
また、保守開発を行う開発者もその間に入れ替わります。
ソースコードを作る際は、このことを踏まえて高品質・低コストで保守開発ができるようにする必要があります。
 
難しい話をするとデザインパターンとかフレームワークとかの話になるのですが、以下のことは新人も含めて最低限心がける必要があります。
 
・適切な変数名やメソッド名を与える
 変数名・メソッド名を与える際は、
 その変数やメソッドが何をするのかわかるような名前にする必要があります。
 例えば、「a」や「hoge」といった変数名は不可で、
 「loopEndFlag」や「commodityCode」といった変数名にする必要があります。
 
 また、現場毎で命名規則が決められていることも多いので、
 それに倣った命名をする必要があります。
 命名規則を無視すると、
 他のソースコードと統一性が取れなくなり読みにくいソースコードになったり、
 影響分析等のためにキーワードで検索する時に引っかからなくなったりします。
 
・適切にコメントを記述する
 コメントを入れることで、その箇所で何をしているのかがわかりやすくなります。
 しかし、コメントを入れれば良いというものではなく、
 意味のあるコメントである必要があります。
 例えば、
 
 /* iが0~11の間処理する */
 for (int i=0;i<12;i++){
 …
 }
 
 といったソースをそのまま日本語にしただけのようなコメントは不可で、
 
 /* 1月~12月の売上高を計算する */
 for (int i=0;i<12;i++){
 …
 }
 
 といった業務的な意味を書く必要があります。
 
 また、ソースコードの先頭には
 「ソース名」「処理概要」「変更日」「変更概要」「変更者」
 といった情報を記述するのが一般的です。
 メソッドの先頭には
 「メソッド名」「処理概要」「引数」「戻り値」「出力され得る例外」
 といった情報を記述するのが一般的です。
 
 コメントの書き方も、現場毎で決まっていることが多いです。
 
・分かりやすいロジックを心がける
 保守開発の際にソースコードのロジックを読み解くことも多いので、
 if文のネスト(if文の中のif文)が多すぎる、
 goto文で制御があちこちに飛ぶ、
 といったロジックが分かりにくくなるような書き方も避けた方が良いです。
 また、if文やfor文等を使う際は、
 インデント(左側のスペース)を適切に入れて、
 構造が分かりやすくなるようにした方が良いです。
 (インデントの入れ方は各言語の入門書を真似れば良いです)
 
 新人の内はあまり気にする必要はありませんが、
 使用する文法も入門書に載っているものを中心にした方が無難です。
 自分の現場で広まっているなら良いのですが、
 そうでないのに新しい文法やマイナーな文法を使うと、
 他の開発者(特に新人)から見て理解しにくくなることがあります。
 
・ハードコーディングは原則禁止
 ハードコーディングとは、
 マスタデータをソースコードの中に持たせることです。
 例えば、
  
 /* 商品コード(野菜) */
 int syohinCodeVegetable = 1;
 
 /* 商品コード(調味料) */
 int syohinCodeSpices = 2;
 :
 :
 :
 
 のような書き方は不可で、商品コードの一覧を持たせたいなら、
 データベースやファイルに持たせてそこから取得するべきです。
 
 マスタデータは、追加や修正や削除が行われることがあります。
 マスタデータをデータベースやファイルに持たせていない場合、
 追加・修正・削除が行われる度に、
 ソースコードを修正しコンパイルする必要が出てきて保守工数が増加します。
 
 更に言うと、マスタコード読み込みのような色々なソースコードで使われる処理は、
 共通処理として別のソースコードに切り出すべきです。
 これをしないと、修正する際に修正漏れが発生する可能性が高くなります。
 大抵の場合、使うべき共通処理は現場毎やプロジェクト毎で決められているので、
 それに従う必要があります。
 
・仕様書とソースコードを合わせる
 仕様書には、ソースコードがどのような意図で作成されているのか、
 他のソースコードとどのような連携をしているのか、
 等の設計思想が記載されています。
 しかし、仕様書がソースコードと乖離していた場合、
 仕様書から調査する時に実際の実装を誤って理解してしまいます。
 そのことにより、保守開発でバグが生まれる原因になります。
 それを防ぐために、ソースコードが仕様書から乖離した時は、
 仕様書もソースコードに合わせて修正するべきです。