コーディング規則　コメント

コーディング規則　コメント

データ

読み そーすこーどこめんと
属性 プログラムTIPS
種類 ソースコード記述の際のルール
能力 EclipeseというIDE(プログラム作るソフトみたいなの)で自動的につけられるコメントの説明
　　 FlashDevelopというIDEで自動的につけられるコメントの説明

概要

ソースコードを書く時、各々が違った書き方でコメントをつけていてはソースコードが見づらくなってしまう。
そこで、コメントのつけ方を統一するためここにコメント付けの一つの例を記述する。
なお、このコメントのつけ方はEclipseのオートコメント機能を使ってつけているものである。

部員全員が同じルールでコメントをつけたり、変数等の名前をつけたらソースコードも見やすくなると思うんだ。
よかったら講習会でこのルールひろめてくれ。

ってJAVA言語作ったおじさんたちが言ってた。
[参考>http://ja.wikipedia.org/wiki/Javadoc]

コメントルール

• 最初に

コメントは基本的に全ての関数に記述する。
クラス、構造体、変数などにはつけなくてもよい。

ここに記述しているコメント例はあくまでも基本的なルールである。そのため、これ以外にも追加でどんどんコメントをつけていくこと。
しかし、このルールを省略したり改造したりしてはいけない。
なぜならこの規則に基づいてIDEがHTMLを作成したりするからだ。
逆に言えば、この規則に基づくことで、自分の作ったプログラムの説明書を自動生成することが出来たりする。

• 例

//**
//* 引数１の値を引数２の値で割り、結果を返す。
//* 
//* @param num1 割られる値
//* @param num2 割る値
//* @return 計算結果の値
//* @Exception 割る値が0の場合、-32768(int型最小値)を返す
//*
//* //メモ　小数点以下の値は切り捨てる
//**
int div(int num1 , int num2){
     //関数内は省略
}

• 解説
• 作成した関数のすぐ上の行からコメントをつける。
• 決められたルールに従って書いたコメントだとすぐにわかるように、「//*」で始めること。
• クラス、構造体、変数、にも同じように「//*」でコメントを記述する

• @param　引数の説明　引数の個数だけ説明を追加する。
• @return　戻り値の説明　どんな戻り値が返ってくるのかを説明する。
• @Esception　例外処理の説明　関数内で発生する可能性のある例外(エラー)とその場合の動作を説明する。例では引数２に０を指定すると0除算が発生して処理が停止してしまうので、戻り値として-32768を返すことでエラーを知らせている。

コメント

• 低レベルなコードでない限りは、コメントがなければ理解できないようなコードはゴミだという考え方もある。シグネチャ -- f (2011-05-19 13:12:44)
• C++ぐらいの言語なら、関数のプロトタイプ宣言だけみたら用法がほぼわかるように書けるし。 -- f (2011-05-19 13:15:22)