はじめに

この記事では、2024ロボコンに制御班として参加し、作成したプログラムの中の終わってるコメントを紹介していきます。
プログラムをよく書く人も、あまり書かない人も楽しんで見ていただいたら幸いです。

良いコメントの書き方は自分で調べたらたくさん出てくると思うので、ここではこれだけは違う！ というコメントを、実際に使用したプログラムをもとに紹介していきます。

悪い例を紹介しているのはあまりないと思うので、是非とも反面教師にして、悪いコメントを書かないようにしてください！

自己紹介

鳥羽商船高専　情報機械システム工学科
4年次以降の選択科目では情報・電気・機械のうち情報系の科目を選択しています。

ロボコンでの担当は、加工(1～2年生)→制御(3～4年生)です。

SEKAI_WORLD関数

皆さんこれを見てどう思いましたか？絶望ですよね！
コメントを見ても何をする関数なのかが全く分かりません...
なので以下の様に修正しました。

正直良いとは言い切れませんが、SEKAI_WORLDに比べたらかなりマシにはなっていると思います。
あくまで個人の意見ですが、コメントには何をする(している) かを書きましょう。
関数は、やりたいことを英語で翻訳し、その結果をそのまま関数名にするのがいいのかなと思っています。
そうすることでより読みやすいプログラムになると思います。

終わりに

まず、最後まで読んでいただき、本当にありがとうございます。
どうでしたか？
おそらく「誰がこんなコメント書くねん（笑）」と思った方がほとんどだと思います...
ですが、皆さんのプログラムの中にも第三者視点で見た際に、「?」となるようなコメントがあるかもしれません。
一度見直すという意味も込めて、次からコメントを書く際は、第三者に理解しやすくすることを念頭に置いてコメントを書きましょう！

おまけ

この記事を書き終わった後に見直していたら、あまりにも短かったのでおまけとしてArduinoのプログラム名も載せておきます。

とても分かりづらくて見るに堪えない...
ここも個人の意見ですが、ファイル名は使用したもの(○○センサーなど)_行ったこと で作成すると後から見直したときに分かりやすいです。