タイトルは私が学生だった頃にC言語のプログラミングを教わった教授の言葉です。名言です。
未だにはっきりと覚えていますし、大変その通りだなと感じます。
今日はこの言葉についてお話ししたいと思います。
コメントの役割
プログラミングにおけるコメントは大きく２つの役割があります。
①プログラムそのものや動作についてのメモ書き
②デバッグ時の補助
いずれの役割でも、上手に活用できるかどうかで成果物のクオリティも制作の工数も大きく変わってくるものです。
(「/*」と「*/」で囲まれたエリアと、同じ行内の「//」以降がコメントです。グレーで表示されてます。)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 | /* Blink Turns an LED on for one second, then off for one second, repeatedly. Most Arduinos have an on-board LED you can control. On the UNO, MEGA and ZERO it is attached to digital pin 13, on MKR1000 on pin 6. LED_BUILTIN is set to the correct LED pin independent of which board is used. If you want to know what pin the on-board LED is connected to on your Arduino model, check the Technical Specs of your board at: https://www.arduino.cc/en/Main/Products modified 8 May 2014 by Scott Fitzgerald modified 2 Sep 2016 by Arturo Guadalupi modified 8 Sep 2016 by Colby Newman This example code is in the public domain. http://www.arduino.cc/en/Tutorial/Blink */ // the setup function runs once when you press reset or power the board void setup() { // initialize digital pin LED_BUILTIN as an output. pinMode(LED_BUILTIN, OUTPUT); } // the loop function runs over and over again forever void loop() { digitalWrite(LED_BUILTIN, HIGH); // turn the LED on (HIGH is the voltage level) delay(1000); // wait for a second digitalWrite(LED_BUILTIN, LOW); // turn the LED off by making the voltage LOW delay(1000); // wait for a second } |
①プログラムそのものや動作についてのメモ書き
プログラム全体についてのメモ書き、例えば、
「このプログラムはこんな動作をします。」
「変更履歴はこうです。誰がいつこういう変更をしました。」
「こんな風に電子部品を接続してください。」(←特にArduinoでは大事な情報)
だったり、ある行についてのメモ書き、例えば、
「この行では温度センサの値を読んでいる」
「ここでの計算はこういう意味がある。」
だったり。
え？そんなことわかりきっているじゃないか、って？
「完成した…と思っていたものを使い始めた。３か月後になんか変な動作をした(=バグがあった)。修正しよう。」
…それぞれの命令や計算式の意味や意図をちゃんと覚えてますか？
…たいていキレイサッパリ忘れてます。『３か月後の自分は他人』なんてよく言われます。
「一度完成したスケッチ(プログラム)を他の人に渡して使ってもらう。」
…あなたの意図を実際にそのスケッチを使う人が読み取れますか？
きちんとマメにコメントを入れてあればすぐに思い出せるし、受け取った人も内容を読み取れます。
コメントにメモ書きでも残っていれば、思い出すきっかけになるでしょう。
コメントを残すのは他人のためであり、未来の自分のためでもあります。
こんなのコメントがなかったら思い出せません。
(むかーしロボコンで使ったコントローラ受信機のスケッチの一部です。何もないと意味不明な命令ですが、「上：前進」という、たったこれだけのコメントで意味が分かります。)
1 2 3 | if(bitRead(rec_data[2],0)==1 && bitRead(rec_data[2],1)==0){ //上：前進 Serial.write(128+MD_Left *4+ 1); Serial.write(send_Speed); Serial.write(128+MD_Right*4+ 1); Serial.write(send_Speed); |
②デバッグ時の補助
本来のコメントとはちょっと違った使い方。
スケッチ(プログラム)を作っていると「思った通りに動かない！」ってことがちょいちょい起きます。よく起きます。しょっちゅう起きます。日常茶飯事です。
当然「思った通りに動かない原因」を突き止めて修正しないといけません。この作業をデバッグといいます。
(不具合を意味するバグは虫という意味があって、昔のコンピュータは内部に虫が入り込んで不具合が出ることがあったことに由来するとか。)
例えば、Arduinoを使って温度計を作ったとします。
35度以上なら赤のLEDが点灯することで熱中症対策するように教えてくれる親切仕様…
…のはずが、うまく動きません。温度の値がおかしいです。
動作の流れとスケッチ(初期化は省略してます)はこんな感じです。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | void loop() { int temp = analogRead(0); //温度センサ読み取り temp = map(temp,0,1023,0,5000); //読み取り値の換算①：一旦電圧に変換 temp = map(temp,1800,300,-30,100); //読み取り値の換算②：温度に変換 if(temp>=35){ //35℃以上？ digitalWrite(13,HIGH); //赤LED点灯 digitalWrite(12,LOW); //緑LED消灯 }else{ digitalWrite(13,LOW); //赤LED消灯 digitalWrite(12,HIGH); //緑LED点灯 } lcd.print(temp); //温度を表示 lcd.print("C"); } |
どこでおかしくなっていて、思い通りの動作をしないのか？
部分ごとにコメントにするとその部分をすっ飛ばして動作するので原因の切り分けができます。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | void loop() { int temp = analogRead(0); //温度センサ読み取り temp = map(temp,0,1023,0,5000); //一旦電圧に変換 // temp = map(temp,1800,300,-30,100); //温度に変換 if(temp>=35){ //35℃以上？ digitalWrite(13,HIGH); //赤LEDON digitalWrite(12,LOW); //緑LEDOFF }else{ digitalWrite(13,LOW); //赤LEDOFF digitalWrite(12,HIGH); //緑LEDON } lcd.print(temp); //LCDに表示 lcd.print("C"); } |
計算式をコメントにしてすっ飛ばして、すっ飛ばした部分を手計算してみたりとか。
3行目の計算をしたところまでならどうやら正しい数値が出ている、4行目の計算をするとおかしくなる、つまり4行目がなんかおかしい！
…って分かっちゃうわけです。
(簡単なスケッチなのですぐわかりますが、関数とかじゃんじゃん使った複雑なスケッチだと原因を切り分けるのも一苦労…体験談です。)
実際にとある温度センサで使える計算式なんですが、正しくは
1 | temp = map(temp,300,1600,-30,100); //温度に変換 |
です。引数(かっこの中の数字)の2つめと3つめの間違いが誤動作の原因でした。
他にもデバッグの常套手段として「変数をシリアル通信でPCに送ってモニタする」ということもありますが、その話はまたいつか。
切り分けのために「シリアル通信でデータを送れ」という命令をコメントアウトする、なんてこともやります。
あと「ベアプログラミング」なんて面白いデバッグ方法もあります。これもまたいつか。
コメントはプログラム書き込み容量を食わない
Arduinoなどのマイコンには「プログラムを書き込める領域」の大きさが決まっていますが、コメントはどれだけ書いてもこの要領を食いません。
同じスケッチでコメントを全削除してみても書き込みソフト(ArduinoIDE)で表示される容量は変わってません。どんどん書いちゃってください。
コメントを制する者がプログラミングを制す
あと、「３か月後の自分は他人」。
ほんとこの言葉通りだと思います。
ガンガンコメントを入れることと、サンプルスケッチなどで他人の入れたコメントを読み解くことがスケッチ作成の上達の助けになってくれます。
…なんて言ってる私もまだまだです。
サンプルスケッチのコメントとか英語だから読みたくないって？Google翻訳があるじゃない！
コメント