コメントの記入スタイルについて
コードの意図を分かりやすくする目的でコメントを書くときに、大目的と小目的を分けて書きたいのですが、皆様はどうしてますでしょうか?
たとえば
//タイマーリセット
timer = 0f;
//スコアリセット
score = 0;
//カウンターを進める
counter++;
というコードブロックがあって、このブロックのマクロ的な意図として「シミュレーションのやり直し時処理」と書き足したい場合、どのように書き加えてますか?
コードの意図を分かりやすくする目的でコメントを書くときに、大目的と小目的を分けて書きたいのですが、皆様はどうしてますでしょうか?
たとえば
//タイマーリセット
timer = 0f;
//スコアリセット
score = 0;
//カウンターを進める
counter++;
というコードブロックがあって、このブロックのマクロ的な意図として「シミュレーションのやり直し時処理」と書き足したい場合、どのように書き加えてますか?
「コードは変更せずに」という条件が付くなら次のようにすると思います。(細かい書き方は異なるかもしれません)
// >>> ○○処理 start
// <<< ○○処理 end
通常は目的ごとにクラスや関数にします。
function retryProcess() {
resetTimer();
resetScore();
incrementCounter();
}
function resetTimer() {
timer = 0f;
}
function resetScore() {
score = 0;
}
function incrementCounter() {
counter++;
}
@konbraphat51
Questioner
「標準的なルール」ということであれば無いと思います。
皆さん仰ってるように、組織のコーディングルールがあれば合わせるのがいいと思いますし、個人等なら好きな表現で目立たせればいいけと思います。
が、強いて言うなら、
/// <summary>
などでコメントをつける(XMLドキュメントコメントといいます)辺りが求めている回答に近いのかな?と思います。
私個人の心がけとしては上記のように、そもそも塊単位のコメントが無くても処理が把握しやすいコーディングをするようにしています。
private void ResetSimulation()
{
timer = 0f;
score = 0;
counter++;
}
みたいな感じです。
質問者さんが組織に属して開発を行っているなら組織のルールがあるのでは? もしなければ、組織で話し合って決める話だと思います。
個人で開発を行っていて、保守にも他人が関わらないということであれば、質問者さんの好みで決めれば良いのではないですか?
このブロックのマクロ的な意図として「シミュレーションのやり直し時処理」と書き足したい場合、どのように書き加えてますか?
変にコメントで分からせようとするより、変数名、メソッド名で自明になるようにすれば良くないですか?ResetSimulation的なメソッドを作って呼べばいいと思います。質問の例のように、処理一行づつにコメントあるのは、無駄に行数増えるだけで逆に読みづらくなり、コメントと処理の二重管理になるので、メンテを続けていくとコメントとの不整合も発生しやすいです。
初期化メソッドに、0やらnull代入してる処理あったら、一行づつ〇〇初期化みたいなコメント書かなくても、初期化用に代入してるのはおおよそ察する事は出来ますよね?読みやすく書かれたソースは、細々とコメントを書かずとも文章のように自然に頭に入ってきます。
メソッド、クラスのドキュメントコメントと、特殊なアルゴリズムや処理を行っている箇所の行頭に概要の説明のコメントを書く程度でいいと思います。
あと、@SurferOnWww さんが書かれているように、組織のコーディングルールがあるのであれば、それに従うのが良いと思います。
皆様ありがとうございます。