技術コラム

スタイル

コメント

ファイルの先頭にコピーライト、およびシステム名等を記述する。なお「ドキュメントコメント」を使用せず、/* (コメント) */の形式を用いる。

/*
 *
 * Copyright (c) 2007 PRIME CO.,LTD All Rights Reserved.
 *
 * システム名: 賃貸管理システム
 * サブシステム名: ユーザ管理
 *
 * 作成者: y.ikehara
 * 日付: 2007/07/17
 * バージョン: 1.00
 * メモ:
 *
 * 履歴:
 * 変更ID 変更日 変更者 変更理由
 * -----------------------------------------------------
 * A001 2007/07/17 y.ikehara 新規作成
 * -----------------------------------------------------
 */

クラス、インタフェース、コンストラクタ、クラスメソッド、インスタンスメソッド、クラスフィールドおよびインスタンスフィールドのコメントでは「ドキュメントコメント」を活用する。

書式

・「///」ではじめる。

・適切なXML形式でなければならない。タグには終了タグも必要。「</XXX>」

タグ

<summary>

 概要について説明を1行程度で明記する。

<remarks>

 機能仕様について説明を明記する。

<param>

 メソッドに引数がある場合、その引数について説明を明記する。

<return>

 メソッドに戻り値がある場合、その戻り値の説明を明記する。

<exception>

 メソッドにが例外をスローする場合、その例外について説明を明記する。

<example>

 使用方法が難解である場合、コーディングサンプルを明記する。

<value>

 プロパティを実装した場合、そのプロパティの説明を明記する。



上記以外のタグもあるが、適宜、必要なものを記述する。

補足

クラス、およびメソッドの定義が始まる直前にコメント行を配置し、そのクラスの機能概要、外部インタフェースについて記述する。

詳細については「NDoc」のドキュメントを参照のこと。

改行のルール

プログラムの見やすさを考慮した場合、1行の長さを適度に制限する必要がある。基本的には80桁以内を目安とし、それを超える場合は行を分割する。行を分割するには、「,(カンマ)」の位置での改行、または演算子(複数の演算子を使用している場合は優先順位の低い演算子)の前で改行を入れる。このような考慮をするだけで、コードの可読性が高まる。

不要メソッド・変数の削除

プログラム内で使用していない変数(インスタンス変数、ローカル変数)は必ず削除する。不要な変数があると、プログラムの可読性が低くなる。同様にメソッドについても使用しないものについては実装しない。後々必要と思えるものについても、必要となったときに実装する。

フォーマット

見た目のフォーマットは非常に大切である。技術者の感性は様々であり、統一は困難であるが基本方針について記述する。

・1行の文字数を最大80桁とする。

・インデントは空白4文字分とする。その際、タブは使用せず空白文字を使用する。

・1行に複数のステートメント(式)を記述しない。

 (変数定義も同様に、1行1変数の宣言とする)

・不等号の向きは左向き(「<」、「<=」)にする。

 (定数と比較する場合は右向きでも可)

・不等号で使用する定数は右側に配置する。

・カンマの後には空白文字を入れる。

・for文の「;(セミコロン)」の後には空白文字を入れる。

・算術演算子(「+」、「-」、「*」、「/」、「%」)の前後には空白文字を入れる。

・算術演算子(「++」、「--」)とオペランドの間には空白文字を入れない。

・代入演算子(「=」、「+=」、「-=」、「*=」、「/=」、「%=」)の前後には空白文字を入れる。

・比較演算子(「<」、「<=」、「==」、「>」、「>=」、「!=」)の前後には空白文字を入れる。

・条件演算子(「||」、「&&」、「|」、「&」、「^」、「!」)の前後には空白文字を入れる。

・シフト演算子(「<<」、「>>」、「>>>」)の前後には空白文字を入れる。

・ビット演算子(「|」、「&」、「^」、「~」)の前後には空白文字を入れる。

・return文では括弧を使用しない。

 (メソッドでなく式であることを明確にする)

文法の基本形

文法の書式・形式についてもフォーマットと同様、技術者の感性に依存する部分である。基本方針について記述する。

・for文で使用するカウンタはfor文のカウンタ宣言にて行なう。

 (for文の外側で宣言しない)

・for文とwhile文の使用用途を明確にする。

 (カウンタを利用する規則的な繰り返しの場合はfor文、それ以外はwhile文を使用する)

・for文で使用するカウンタの初期値は「0」を基本とする。

 (配列の添字は「0」からである.カウンタはインデックスの役割で使用する場合が多い)

・制御文(「if」、「else」、「while」、「for」、「do while」)での「{}」は省略しない。

 (1行の式でも省略しない.機能追加時のバグ発生を避けられる)

・ローカル変数は利用する直前で宣言する。

 (C言語のように関数の入り口で宣言しない)

 

△Vol.1 コーディングルールへ戻る

2009年6月17日 18:08