世の中には各種のプログラミング言語があり、コメントの文法も様々ある。
わりと一般的なのは C#, C, C++ などの
// // コメント //
や
/*
コメント
*/
かな。
これらのコメントをソースコードに書く際に、これまた各人多様な方式があると思う。
当記事では、各種のプログラミング言語を経験してきたワテが実践しているコメントの書き方を紹介したい。
コメントはプログラムの右余白に書く
良く参考にさせて頂いている
さんのサイトでは、例えば、
のC#版ならこんなふうにコメントが書いてある。
//”C:\test1.txt”をShift-JISコードとして開く
System.IO.StreamReader sr = new System.IO.StreamReader(
@”C:\test1.txt”,
System.Text.Encoding.GetEncoding(“shift_jis”));
//内容をすべて読み込む
string s = sr.ReadToEnd();
//閉じる
sr.Close();
//結果を出力する
Console.WriteLine(s);
ワテも以前はこういうふうに、コメントとソースコードをミックスして書くやり方をしていた。
しかし、最近のワテは、以下のようにコメントを書いている。
//”C:\test1.txt”をShift-JISコードとして開く
System.IO.StreamReader sr = new System.IO.StreamReader(
@”C:\test1.txt”,
System.Text.Encoding.GetEncoding(“shift_jis”));
string s = sr.ReadToEnd(); //内容をすべて読み込む
sr.Close(); //閉じる
Console.WriteLine(s); //結果を出力する
つまり、コメントは殆ど全てソースの右側の余白に書くようにしている。
コメントを記述する時の注意事項 – ワテの場合
要するに、そのブロックの機能や目的などを記載する場合に限り、例外的に左端から見出しのように書くこともあるが(上例の1行目)。
それ以外のコメントは、ソースコードの右側に書く。
コメントは必要最小限で簡潔に書くのが良い。
古いコメントはドンドン消して、常に最新ソースコードの内容を説明するコメントを書く（更新する）。
分かり切った処理でも、後で見直したときに忘れている場合もあるので、何故そういう処理をしているのかなどをコメントに書くようにしている。
たとえば if文を使った場合、
if(...){
処理
}
だと何故 else{…} の処理が無いのかを説明するようにしている。
プログラムを書いている時には頭がさえているので else が無いのは分かり切っていても、後でデバッグなどで見直したときに何でここに else が無いんや？
これがバグの原因か？などと混乱する場合もあるからだ。
そういう無駄を排除するためにも、else を省略する場合には必ず理由を書くようにしている。
でもワテの場合は、基本的にはelseは省略せずに書くようにしている。
基本的には elseは省略しない
本来は省略する予定のelseを追加しても、そのelseブロックではする事が無い。
それはそれで問題は無い。
追加したelseブロックの目的は、そのelseブロックでは今の場合には何もする必要が無い理由を説明する為だからだ。
具体的には以下のようにしている。
if(...){
// ここで・・・の処理をする
実際の処理
}else{
// 今の場合はここでは何もしない。理由は・・・
}
要するに、elseブロックの中にズラズラと説明をコメントで残すようにしている。
ワテがコメントを右側余白に書く理由
なぜ右側にコメントを書くようになったかというと、後でデバッグや改良でコードを見直す場合、基本的にはソースコードだけを目で追って処理の流れをつかむのが良いと思うからだ。その為にはコメントが逆に目障りになる。
ソースコードを分かり易く書くように心掛けていると、コメントが無くても処理の意味が理解出来てスラスラと処理の流れをつかむことができる（理想的には）。
でも、時間が経っていて頭が鈍っている時の手助けの為にコメントが役立つのだ。
そういう理由でワテは右側にまとめてコメントを書くのだ。
コメントいろいろ
そのブロックの説明の為に見出しのように大きくコメントを書く場合には、いろんな書き方が有るようだ。
例えばこんな感じか。他にも色々あると思う。
static void Main(string[] args)
{
/*****************************************
*
* コメント
*
* ワテは昔はこんなふうに書いていた
****************************************/
/*
*
* コメント
*
* 或る時期、こんな形式も使っていた。
*/
/**
**
** コメント
**
** C#だと何故か緑色になる
**/
///////////////////////////////////////////////
//
// コメント
//
// あまり好きでは無い。
///////////////////////////////////////////////
/*=============================================*/
/* */
/* コメント */
/* */
/* */
/*=============================================*/
//______________________________________________
// このブロックは○○の処理
//
// ちょっと変かな。ワテは時々こんな書き方もする
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
}
まあ、色んなコメント記述スタイルがあるので、色々試して自分に合ったスタイルにするのが良いだろう。
プログラミングスタイルに関して – ワテの意見
プログラミングにはその人の性格が良く現れる。
几帳面な人、ズボラな人、神経質な人、大らかな人、良く分からん人、、、などなど
自分流のプログラミングスタイルを身に付けるのは良い事だと思う。
でも、自己流のスタイルに固執するのは良くないと思う。
例えば、forループは
for(int i=0;i<10;i++){
・・・
}
ではなく、
for(int i=0;i<10;i++)
{
・・・
}
にするべきだとか。
そう言う些細な事にこだわらないほうが良いだろう。
と言うのは、ソースコードの表示スタイルなんて、エディタの設定で簡単に変更出来るからだ。
自分はこう言うスタイルだと決めていても、他人のソースコードはそのスタイルになっているとは限らない。
なので、例えばforループが、
for( int i=0 ; i<10 ; i++ )
{
・・・
}
だろうが、
for ( int i=0 ; i<=9 ; i=i+1 )
{
・・・
}
だろうが、
for(int i=0;i<10;i++){・・・}
だろうが、どんなforループに出くわしても、そのスタイルを気にするのではなくて、その処理内容を理解する能力を身に付けるほうが重要だ。
神経質な人の場合、カンマとかセミコロンの前後の半角スペースの有無でさえ気になる人もいる。
確かに英文ではカンマの前には半角スペースを入れない。
悪い I have iPhone,iPod,and iPad.
悪い I have iPhone , iPod , and iPad.
でも例えばプログラミングの世界では、カンマはこんな使い方もする（ワテの場合）。
string[] arr={
"one" , "two" , "three" ,
"four" , "five" , "six" ,
"seven" , "eight" , "nine" ,
"ten"
}
でも、英語圏の人とか、神経質な人が見ると、こういうカンマの使い方が気になるようだ。
カンマの前にスペースを入れてはいけない！
まあ、カンマをこんなふうに使うのが良いかどうかは意見が分かれるとは思うが、ワテは使う。
それに、世の中、もっとヘンテコなプログラミングスタイルもあると思うので、どんなヘンテコなプログラミングスタイルを見てもそんな事では動じない悟りの境地に到達するのがワテの理想だ。
そして、そのプログラムの処理の中身をスラスラと理解出来る能力を身に付けたい。
そう言う者にワテは成りたい
宮沢賢治か！？
まとめ
当記事では、ワテ流のコメントの記述方法に付いて説明した。
またif文でelseは滅多に省略しない理由も説明した。
elseは省略せずに中身が空のelseブロックを追加して、なぜ空になるのかをコメントで説明しておくと、後で見直した場合に分かり易い。
自分流のプログラミングスタイルを身に付けるのは良いが、固執するのは良くない。
他人に強要するのは更に良くない。
どんなプログラミングスタイルでも受け入れる広い心が必要だ。
以上、ワテ流コメントの書き方でした。
なお、
しても、意外なものが沢山出て来る。何でやねん？
追記（2016-03-03）
もあります。
コメント