@konbraphat51

Are you sure you want to delete the question?

Leaving a resolved question undeleted may help others!

コメントの記入スタイルについて

コードの意図を分かりやすくする目的でコメントを書くときに、大目的と小目的を分けて書きたいのですが、皆様はどうしてますでしょうか?

たとえば

//タイマーリセット
timer = 0f;

//スコアリセット
score = 0;

//カウンターを進める
counter++;

というコードブロックがあって、このブロックのマクロ的な意図として「シミュレーションのやり直し時処理」と書き足したい場合、どのように書き加えてますか?

0 likes

5Answer

「コードは変更せずに」という条件が付くなら次のようにすると思います。(細かい書き方は異なるかもしれません)

// >>> ○○処理 start

// <<< ○○処理 end

通常は目的ごとにクラスや関数にします。

function retryProcess() {
  resetTimer();
  resetScore();
  incrementCounter();
}

function resetTimer() {
  timer = 0f;
}
function resetScore() {
  score = 0;
}
function incrementCounter() {
  counter++;
}
2Like

Comments

  1. @konbraphat51

    Questioner

    ご回答ありがとうございます。まさにそれを知りたかったです。
    ちなみに`>>>`の記法には何らかの呼称はあるでしょうか?
  2. 呼称は無いです。特定のルールを意識したものではないので。
    C#は詳しくないのですが、これまで経験してきた言語ではそのようなコメントについての標準的なルールに心当たりは無いですね。
    ブロックの開始と終了が分かれば良い、という程度です。`>>>`にこだわらなくてもいいと思います。

    個人的にはこの部分の表現方法やルール化を頑張るくらいなら、コメント無しで表現できるよう頑張りたいところです。

「標準的なルール」ということであれば無いと思います。
皆さん仰ってるように、組織のコーディングルールがあれば合わせるのがいいと思いますし、個人等なら好きな表現で目立たせればいいけと思います。

が、強いて言うなら、

  • ソースコードを見ればわかる行単位のコメントはつけない
  • コメント無しで理解しやすいコードを書く
  • コードだけで表現しづらい理由や背景や意図などに絞ってコメントを書く
  • 大きな処理の塊はメソッド化する(最近のC#ならローカル関数も活用できます)
    • メソッド名として処理の概要を表現する
  • 非ローカルメソッドには /// <summary> などでコメントをつける(XMLドキュメントコメントといいます)

辺りが求めている回答に近いのかな?と思います。

私個人の心がけとしては上記のように、そもそも塊単位のコメントが無くても処理が把握しやすいコーディングをするようにしています。

private void ResetSimulation()
{
    timer = 0f;
    score = 0;
    counter++;
}

みたいな感じです。

2Like

Comments

  1. あまり使わないので忘れていましたが、C#であれば `#region ○○処理` `#endregion`というのもあります。
    これが求めているものかもしれません。

質問者さんが組織に属して開発を行っているなら組織のルールがあるのでは? もしなければ、組織で話し合って決める話だと思います。

個人で開発を行っていて、保守にも他人が関わらないということであれば、質問者さんの好みで決めれば良いのではないですか?

0Like

このブロックのマクロ的な意図として「シミュレーションのやり直し時処理」と書き足したい場合、どのように書き加えてますか?

変にコメントで分からせようとするより、変数名、メソッド名で自明になるようにすれば良くないですか?ResetSimulation的なメソッドを作って呼べばいいと思います。質問の例のように、処理一行づつにコメントあるのは、無駄に行数増えるだけで逆に読みづらくなり、コメントと処理の二重管理になるので、メンテを続けていくとコメントとの不整合も発生しやすいです。

初期化メソッドに、0やらnull代入してる処理あったら、一行づつ〇〇初期化みたいなコメント書かなくても、初期化用に代入してるのはおおよそ察する事は出来ますよね?読みやすく書かれたソースは、細々とコメントを書かずとも文章のように自然に頭に入ってきます。

メソッド、クラスのドキュメントコメントと、特殊なアルゴリズムや処理を行っている箇所の行頭に概要の説明のコメントを書く程度でいいと思います。

あと、@SurferOnWww さんが書かれているように、組織のコーディングルールがあるのであれば、それに従うのが良いと思います。

0Like

Your answer might help someone💌