前提

ゲームのプログラミング向け。業務システムとかに向けた話じゃないです。
筆者はゲームプログラマ。主にC++を想定
ベテランというほど長くプログラマをやっているわけではない。30代前半
- 内容についてのツッコミなど歓迎。というかもっと整理されたいい記事を書いてくれる人がいたらうれしい
その現場のルールとかが優先
Doxygenとか使ってるならちゃんとそれに合わせる
- ここではとりあえず本質的じゃなさそうな記法については飛ばす。「どんな環境でもなりたちそう」なところを優先して書く
コメントの位置とか改行フォーマットとかも現場次第なところがある
AIによる支援を受けながらコーディングを行う時代には未対応

サンプル

/**
このファイターの視点から、指定した時間が経過した後の相手との距離を予測する
other 距離を予測したい相手
second 予測したい時間（秒）
返り値は予測した距離(m)
*/
float NankaFighter::PredictDistance( const NankaFighter* other, float second )const
{
    if( other == nullptr ){
        assert(false);
        return 0.0f;
    }
    if( second < 0.0f ){
        assert(false)
        second = 0.0f;
    }
    float resultDistance = 0.0f;
    if( IsDefeated() ){//倒されている場合
        resultDistance = PredictDistanceWhileDefeated( other, second );
    }
    else if( IsSleeping() ){//寝てる場合
        resultDistance = PredictDistanceWhileSleaping( other, second );
    }
    else {//通常の処理
        resultDistance = PredictDistanceStandard( other, second );
    }
    //距離が負の値になるのはおかしい
    if ( resultDistance < 0.0f ){
        assert(false);
        resultDistance = 0.0f;
    }
    return resultDistance;
}

色々とポイント補足

関数のコメントは、「何を入れて」「何を返すのか」は関数名とかでわかると思っても書いておいた方がいい
- 必要なさそうでも書くクセをつけておいた方がいい
- intやfloatのようなプリミティブ型を使う場合、単位などにも気を付けた方がいい
- 例えばこのサンプルの場合、変数名に second ではなく time を使ってしまうと単位が秒なのかミリ秒なのかフレーム数なのかと混乱を起こす
関数名は、昔はある程度短い方がいいと言われていましたが、今はIDEが優秀なのとPCディスプレイもコードの規模も大きい時代なので長くしてわかりやすくした方がいいはず
スマートポインタを使えるなら使っておいた方がいいはずだけど、ここでは余分な情報を減らすため使わない
- めちゃくちゃ大量にループを回す場合にはオーバーヘッドが無視できないことがあり、使わないことはたぶんある
constメンバ関数。つまり、副作用が無い関数
- 可能な限り関数は副作用が無い方がいい
- 逆に副作用がある関数は、できるだけ副作用を起こす以外の処理が無い方がいい
  - どんな副作用を起こすか決める関数と、実際に副作用を起こす関数を別にする……とか
最初のif文2つ（ガード節）
- うっかりミスを回避
- もしうっかりミスが発生しても、ゲームの場合はクラッシュすることだけを回避して「それなり」の動作をしてもらった方がいい場合が多い
次のif文とif else
- 状況によってそもそも行うべき処理が違う場合、各if文の中で処理を書くのではなくそもそも別の関数を呼び出すべき
- パターンとしては「処理A・処理B・通常処理」か「処理A・処理B・例外処理」のどちらかの並びになることが多いはず
- 後からパターンを増やすときに、他のパターンと並列（同じネストの深さ）で増やせるように
最後のif文
- 結果がおかしくないかチェック
- ここではとりあえず0未満の時だけチェックしているが、別のバリデーション関数にした方がいいかも
- 最初のガード節でもそうだが、問題のある値になった場合に0ではなく「非常に大きい値」を返した方がいいかもしれない
  - そこはそのゲームの仕様次第
コメントはガンガン書いておくと、後から検索したりして探しやすい。
- 「コメントのつけすぎ」に警戒する人がたまにいますが、コメントをつけすぎる人を見たことはありません。コメントが全然足りない人は山ほど見たことあります。つけすぎて困ることより足りなくて困ることの方が圧倒的に多いです。

悪い例

    float param;//パラメータ

理由

変数は全て何らかのパラメータです。「何のパラメータなのか」を変数名とコメントに書かなければいけません。

ゲームプログラマとして働き始めたくらいのレベルの人に届けたい、こういう感じのコードとコメントを書いてほしいというメモ書き

前提

サンプル

色々とポイント補足

悪い例