質問をすることでしか得られない、回答やアドバイスがある。

15分調べてもわからないことは、質問しよう!

ただいまの
回答率

89.96%

プログラムのコメントの仕方がわかりません。

受付中

回答 3

投稿

  • 評価
  • クリップ 0
  • VIEW 1,107

shiroooooo

score 10

以下のプログラムにコメントを書くとしたらどのように書いたらよいでしょうか?
途中からですがお願いします。


#include<stdio.h>
#include<math.h>

int PutData(int x[3],int mode);
int matrix_mul(double a[3][3],double b[3],double c[3]);

int main()
{
    double vb[3];
    double a[3][3];
    double wh[3];
        double adj[3]={0.682,0.682,0.682};
    double Rb=80.0,Rw=24.0;
    int x[3];
        int tm=0;
    int i;

    a[0][0]=1.0;    a[0][1]=0.0;        a[0][2]=Rb;
    a[1][0]=-0.5;    a[1][1]=sqrt(3.0)/2.0;    a[1][2]=Rb;
    a[2][0]=-0.5;    a[2][1]=-sqrt(3.0)/2.0;    a[2][2]=Rb;

    for(tm=0;tm<1000;tm++)
    {
    vb[0]=200.0;
    vb[1]=0.0;
    vb[2]=0.0;

    matrix_mul(a,vb,wh);

    for(i=0;i<3;i++)
    {
    x[i]=(int)(adj[i]*wh[i]/Rw);
    }
    if(PutData(x,1)<0)
    break;
    }
    return 0;
}

int matrix_mul(double a[3][3], double b[3], double c[3])
{
    int i,j;
    
    for(i=0;i<3;i++)
    {
        c[i] = 0.0;
        for(j=0;j<3;j++)
        {
            c[i] = c[i]+a[i][j]*b[j];
        }    
    }
    
    return 0;
}
//.dw    0b0CCCCCBBBBBAAAAA
int PutData(int x[3],int mode)
{
    int i,j,buf;
    char bin[6];

    for(i=0;i<3;i++)
    {
    if(x[i]>15 || x[i]<-15)
    {
    printf("DATA ERROR! x[%d]=%d\n",i,x[i]);
    return -1;
    }
    }

if(mode!=0)
{
    printf("\t.dw\t0b0");
    for(i=2;i>=0;i--)
    {
        if(x[i]>=0)    buf=x[i];
        else    buf=32+x[i];
        for(j=0;j<5;j++)
        {
            bin[4-j]=buf%2+'0';
            buf/=2;
        }
        bin[5]=0;
        printf("%s",bin);
    }
    printf("\n");
      }
else
{
    printf("%d,%d,%d\n",x[0],x[1],x[2]);
}
return 0;
}
  • 気になる質問をクリップする

    クリップした質問は、後からいつでもマイページで確認できます。

    またクリップした質問に回答があった際、通知やメールを受け取ることができます。

    クリップを取り消します

  • 良い質問の評価を上げる

    以下のような質問は評価を上げましょう

    • 質問内容が明確
    • 自分も答えを知りたい
    • 質問者以外のユーザにも役立つ

    評価が高い質問は、TOPページの「注目」タブのフィードに表示されやすくなります。

    質問の評価を上げたことを取り消します

  • 評価を下げられる数の上限に達しました

    評価を下げることができません

    • 1日5回まで評価を下げられます
    • 1日に1ユーザに対して2回まで評価を下げられます

    質問の評価を下げる

    teratailでは下記のような質問を「具体的に困っていることがない質問」、「サイトポリシーに違反する質問」と定義し、推奨していません。

    • プログラミングに関係のない質問
    • やってほしいことだけを記載した丸投げの質問
    • 問題・課題が含まれていない質問
    • 意図的に内容が抹消された質問
    • 広告と受け取られるような投稿

    評価が下がると、TOPページの「アクティブ」「注目」タブのフィードに表示されにくくなります。

    質問の評価を下げたことを取り消します

    この機能は開放されていません

    評価を下げる条件を満たしてません

    評価を下げる理由を選択してください

    詳細な説明はこちら

    上記に当てはまらず、質問内容が明確になっていない質問には「情報の追加・修正依頼」機能からコメントをしてください。

    質問の評価を下げる機能の利用条件

    この機能を利用するためには、以下の事項を行う必要があります。

回答 3

+3

文法や形式については別途。「なにをどうかくか」という観点から回答します。

ソースコードコメントにはいくつかの種類があります。以下、種類ごとに、どのように書いたらよいかまとめます:

1. 仕様を説明するもの
クラスやメソッド、関数などの利用者にむけて、これはこういうものだよ、こういう使い方をしてね、というメッセージを書きます。
各関数の前に、「この関数は**をする。**、**、**を引数として受け取り、**を返す。ゼロを返すことはない。**の場合は**となる。」といった要領で書きます。
Doxygenなどのツールで文書化することができます。 http://www.doxygen.jp/docblocks.html

2. 意味を説明するもの
ソース中に現れる、ぱっとは意味がわかりにくい記述に対して意味を補足します。

  • double adj[3]={0.682,0.682,0.682}; 
という行に対し、「この 0.682 とは**という意味である」ということを記述します。
ほかに設計書や解説書があるなら、「画面設計書 5.6.2 の記載に基づき」のように根拠を示す方法もあります。
定数として別に定義しておき、その定数名を工夫するという方法もあります。

  • printf("\t.dw\t0b0");
という行に対し、「この.dwとは**という意味である」ということを記述します。……ってこれ、アセンブラコードを生成してるんですかね? 読む人にとってそういった文脈が明らかであれば、.dwなんて説明するまでもないでしょうからコメントはいらないでしょうね。


3. 意図を説明するもの

ソース中に現れる、ぱっとは意図がわかりにくい記述に対して意図を補足します。

たとえば、私は
  • printf("\t.dw\t0b0");
という行に対し、なぜ0bなのか疑問に思いました。
  • printf("\t.dw\t0x%x%x%x\n", x[0],x[1],x[2]);
でいいんじゃないか、と。そこで 「0bにしている理由は**である」というコメントがあれば疑問はなくなります。

ほかには、その下の else 節では、単純に printf("%d,%d,%d\n",x[0],x[1],x[2]); としていますが、そんなんでいいのか? と思いました。きっと仕様書のどこかどおりに書いているんだとは思いますが、それなら「仕様書 5.6.2に従い」といった補足コメントがあるとうれしいです。

古い資料ですが、 Scott W. Ambler による「Writing Robust Java Code」の一節を紹介します。
http://www.alles.or.jp/~torutk/oojava/codingStandard/writingrobustjavacode_pidid93_c1.html#doc1_id171
コメントには、なぜそうなのかを書く。コードを読めば分かることを書かない
基本的に、コードの一部分を見ればそれが何かを理解することはできる。 例えば、以下の例1.1のコードを見て、$1000以上の注文については5%ディスカウントされることは理解できる。なぜそうなのか? 大きな注文ではディスカウントがつきものだというビジネスルールがあるのだろうか? 大きな注文に時間限定サービスがあるのか、それともずっとサービスがあるのか? これを書いたプログラマーの気前がよかったのか?  どこかソースコード中か別な文書にドキュメントされていない限り、なぜなのかを知ることはできない。


4. ソースコード上のマーカーとして
統合開発環境の中には、// TODO や // FIXME といったコメント行を見つけてブックマークリストを作ってくれたり、 //@formatter:off と書くと、それ以降はオートフォーマットしないでくれたりといった機能を持つものがあります。そういう機能を使うためにコメントを書くような場合もあります。


「リーダブルコード」いい本ですよね。おすすめです。

投稿

編集

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

+2

リーダブルコードを読むことをオススメします。

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

-2

Cですね。 コメントは /* で初めて */ で終わらせます。
たとえば
vb[0]=200.0; 
を100にして、でも元の200を残したいなら
/* vb[0]=200.0; */
vb[0]=100.0; 
とかきます。

http://www.geekpage.jp/programming/c/comment.php

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

15分調べてもわからないことは、teratailで質問しよう!

  • ただいまの回答率 89.96%
  • 質問をまとめることで、思考を整理して素早く解決
  • テンプレート機能で、簡単に質問をまとめられる

同じタグがついた質問を見る