プログラムを書く時の分かりやすいコメントの書き方が知りたい

今記事に関してはパソコンからの閲覧を推奨しています。

---

こんにちは、堀井です。

最近個人でも（特にExcelVBAで）プログラムを書いて遊んでいるのですが、上手いコメントの書き方がわからない！！！

もちろん書いて試しての試行錯誤を繰り返せばいいのですが、特に職業訓練でプログラミングを勉強していた頃なんて

int main (void){
    int a = 1;
    for (int i=0; i<10; i++){
        i+=a;
        printf("i=%d",i);
    }
    printf("出力終了\n");
    return 0;
}

みたいな感じで書いており、スペースの上手い空け方もまともに分からなかったので当時はより一層汚いコードが量産されていました。

こんな状態から試行錯誤しようが、精々この程度が関の山だと思います。

int main (void){
    int a = 1;

    //足し算して出力する
    for (int i=0; i<10; i++){
        i+=a;    //インクリメント
        printf("i=%d",i);
    }
    printf("出力終了\n");

    return 0;
}

もはやどこが変わったのかわからないレベルですがコメントと改行を少し入れました。

インクリメントなんて書かなくてもわかるよね。

---

さて、そんな状況だった頃がありましたし、今だにより良いい書き方と言うのは試行錯誤中です。

ただ、今職業訓練で勉強しているような超初心者の方からすれば参考になるでしょうか。

【補足1】
ちなみに良書と言われるこの本を読んでもよくわからなかった自分が書いていますので、もっといい書き方もあると思っています。

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

【補足2】
なお以下のコードはpaiza.ioにて期待通りの動作をすることを確認しています。

【補足3】
そして今コードを書くに当たり、こちらの「プログラム言語 C の推奨されるスタイルとコーディング規範」を参考にさせていただいています。

---

ファイル数が増えると何が何だかわからなくなるのでルールを決めてコーディングするのがいいですよね。

/************************************************/
/*  outline::                                   */
/*      hoge.c                                  */
/*      Do nothing                              */
/*----------------------------------------------*/
/*  author::                                    */
/*      foo                                     */
/*  ver::                                       */
/*      1.00                                    */
/*  reference::                                 */
/*      bar                                     */
/************************************************/
/************************************************/
/*  FILE INCLUDE                                */
/************************************************/
#include <stdio.h>

/* #include "cmn/hoge.h" */

/************************************************/
/*  DEFINITION                                  */
/************************************************/
#define SPAM 1
#define MAX( a, b ) ( a > b ? a : b )
#define MIN( a, b ) ( a < b ? a : b )

typedef int    INT;
typedef double DBL;
typedef char   CHR;

typedef struct {
    CHR name[10];
    INT age;
    DBL workTime;
} info;

enum classroom {
    CLASS_A,
    CLASS_B,
    CLASS_NUM   /* total */
};

/************************************************/
/*  PROTOTYPE DECLARATION                       */
/************************************************/
INT main ( void );
INT getNum ( void );

/************************************************/
/*  GLOBAL DECLARATION                          */
/************************************************/
extern INT fizz;

INT buzz;

static INT fuga;

/************************************************/
/*  GLOBAL FUNCTION                             */
/************************************************/
/************************************************/
/*  Function name::                             */
/*      main                                    */
/*  outline::                                   */
/*      none                                    */
/*  argument::                                  */
/*      none                                    */
/*  return value::                              */
/*      0                                       */
/************************************************/
INT main( void ) {
    INT hoge;
    
    hoge = getNum();
    
    printf("クラス数は%dクラスです\n", hoge);
    
    return 0;
}

/************************************************/
/*  Function name::                             */
/*      getNum                                  */
/*  outline::                                   */
/*      none                                    */
/*  argument::                                  */
/*      none                                    */
/*  return value::                              */
/*      CLASS_NUM                               */
/************************************************/
INT getNum ( void ) {
    printf("合計クラス数を返します\n");
    
    return CLASS_NUM;
}

もちろんサンプルコードですのでtypedef宣言をはじめ、意味わからないことやってますね。

コメント部分と、書く順番だけ参考にしていただければいいかなと思っています。

短めですが、それではまた次回。