＜Ｋｅｎ３、ソースのコメントについて考える＞
目次 1.はじめの挨拶 2.と、その前に、ご教授下さいファンに一言？ 3.ソースのコメントについて 4.おわりの挨拶 枠外：読者からの補足メールいただきました（感謝です） ---------------------------------------------------------------------------- /* * １.はじめの挨拶 */ こんにちは。 三流ＰＧのＫｅｎ３です。 このメールマガジンは脚色されているので、 ご注意を、、、（実際と違う内容も含まれているので、） バーチャルカンパニーです。（←それにしては、リアル？） 今回は、 前回、ＣからＶＢへの移植？の質問を受けた時、 なんとなくソースファイルのコメントについて書きたくなったので、 書きます。 ＊みなさんの立場で読んで、笑ってください。 疑問・感想、、指摘、、あったら、メール下さい。 /* * ２．と、その前に、ご教授下さいファンに一言？ */ ソースのコメントのこと書く前に、前置き、続きます。 >私、変わり者なので（そんなん、いまさら言わなくてもわかってるって？） >ご教授下さい、よろしくお願いします >の質問より >解説できるもんならやってみろ >のほうがなんとなく好きなんだよなぁ、、、 と 前回書いたら、 教えてもらうのでご教授下さいがいいのでは？（妥当では？） と ご教授ファンの人からや、 初対面の作者に馴れ馴れしく質問書く人なんか居る？ と 一般常識さんから メールをいただきました。 確かに、馴れ馴れしく 、 軽いノリの質問 を 初対面の人に書けない気持ちは、わかりますが、 ご教授下さい、、、まで言わなくてもいいでしょ？が私の素直な気持ちです。 インターネットのマナー？に質問時は、ご教授下さいって載ってるのなぁ？ >解説できるもんならやってみろ は、Ken3流の言いすぎですが、 私は軽いノリの質問のほうが好きです。 まぁ、三流君Ｋｅｎ３の感じ方なので、あまり気にしないでください。 でも、ご教授下さい、、、は、好きじゃないなぁ（オイオイしつこいって、、） /* * ３.ソースのコメントについて */ 人が作成したプログラムや自分が過去作成したシステムを 移植する時や解析時、 仕様書がしっかりも大切ですが、 ソースファイルにキレイナコメントが載っていると 後々わかりやすいと思います。 （＊ニセのうそつきコメントにだまされた、、って逆作用もあったけど、、） 下記、Ｃで昔作成したソースの一部です。（土曜日ハマッタ工場の修正） /* テンポラリファイル作成 */ #include#include #include #include void sk_fsave(fname) char *fname; { FILE *ifp; /* 入力ファイルポインタ */ FILE *ofp; /* 出力ファイルポインタ */ int i, n, c; int ret, sw; long r_cnt; char in_buf[40]; /* 入力バッファ */ char out_buf[40]; /* 出力バッファ */ static char cr_lf[2] = { 0x0d, 0x0a }; memset(&in_buf[0], 0x00, 40); ifp = fopen(fname, "r+b"); /* ファイルオープン */ ofp = fopen("temp", "w+b"); r_cnt = 0L; ret = fread(&in_buf[0], 32, 1, ifp); /* データ１件読み込み */ while(ret == 1) { /* データがなくなるまで */ if(in_buf[19] == '0') { /* 転送チェック */ memset(&out_buf[0], ' ', 32); memcpy(&out_buf[0], &in_buf[0], 11); n = fwrite(&out_buf[0], 30, 1, ofp);/* テンポラリへ出力 */ n = fwrite(&cr_lf[0], 2, 1, ofp); /*ファイルポインタを戻す */ sw = fseek(ifp, r_cnt * 32L, SEEK_SET); in_buf[19] = '0'; n = fwrite(&in_buf[0], 30, 1, ifp); /* フラグの書き込み */ n = fwrite(&cr_lf[0], 2, 1, ifp); sw = fseek(ifp, r_cnt * 32L + 32L, SEEK_SET); } memset(&in_buf[0], 0x00, 32); ret = fread(&in_buf[0], 32, 1, ifp); /* データ１件読み込み */ r_cnt = r_cnt + 1L; } fclose(ifp); /* ファイルクローズ */ fclose(ofp); } みなさんからも、参考意見いただきたいのですが、 私が感じたことを書きます。 （＊例がＣ言語ですが、ＶＢＡなどでも同様だと思います） ア．関数の情報として必要な項目は？ 頭に記載すべき？情報は？ void sk_fsave(fname) char *fname; { としか、書いてない。 a.処理概要が必要？（フラグの立っていないデータを抽出するなど？） b.入力引数の説明(char *fname;まぁ、みればなんとなくわかるけど) c.リターン値（このサンプルでは、無いけど） イ．あたりまえのコメントはいらない？ 私がそうなのですが、 簡単にコメント付けられる部分にだけ、コメントつけてます。 FILE *ifp; /* 入力ファイルポインタ */ FILE *ofp; /* 出力ファイルポインタ */ ifp = fopen(fname, "r+b"); /* ファイルオープン */ ofp = fopen("temp", "w+b"); など、、、 このへんは、みればそのままなので、コメントはいらない？ まぁ、さびしいので、あってもいい？って考えもありますが、、、 極論だと、 i++; i = i + 1; // iを１増やす なんてコメントはイラナイよね。。。 ウ．素直な日本語を書こう？ ret = fread(&in_buf[0], 32, 1, ifp); /* データ１件読み込み */ while(ret == 1) { /* データがなくなるまで */ さすがにここを、retが1の間ループとは、書かなかったが、 /* データがなくなるまで */ と書いてます。。。これでもいいのだが、 while( fread(&in_buf[0], 32, 1, ifp) == 1 ) { データが読めている間と書いた方が、わかりやすかったかも？ 現在の自分から未来の自分自身へ ただ、動くだけじゃなく、キレイナソース書こうね。。。 またまた、言うは容易く行い難し、、、って言葉しってる？ あと、仕様書もセットでね。。（ハイハイ、、、） ソース、コメント関係の参考意見、待ってます。 ｅｔｃ.バグ見っけ、、（過去のナマイキなＫｅｎ３さんへ） sw = fseek(ifp, r_cnt * 32L, SEEK_SET); in_buf[19] = '0'; n = fwrite(&in_buf[0], 30, 1, ifp); /* フラグの書き込み */ 昔の自分へオイオイ、、、、 in_buf[19] = '0'; じゃ、フラグ立ってなくて、次来た時もｔｅｍｐファイルに書いちゃうじゃん in_buf[19] = '1'; じゃないの、、、まぁ、いっか。。。 クレームないし、中間チェック機能を使っていないのでしょう。 ＊このファイル作成タイミングは、作業終了時に（１直２直交代時？） チェックリスト出力ようのファイルを生成、 （出力済みのデータを出さないためにフラグを立てているんだけど。。。） /* * ４.終りの挨拶 */ ヤッパ、こっちの愚痴マガに書くほうが、落ち着く。 なんて言ってないで、、、、 三流ＰＧ Ｋｅｎ３でした。
枠外通信？ 愚痴マガ読者のＴさんより、アドバイス、補足メールいただきました '----------------------------------------- >こんにちは、愚痴マガ読者の＊＊です。 > >いつも楽しく読ませてもらっています。 >説明入れておきます。 > >> > #includeこのヘッダーが有れば、ＬＳＩコンパイラでも使 >える？ >> >> ＬＳＩコンパイラでも使える？ >> これは、厳しいかも？ > >コード生成の方法が違うので、16/32ビットに関わらず、LSI-Cでは使えません。 > >> > #include 同上 >> >> なに？ > >これは解りません。少なくとも私の持っているコンパイラにはそのような >ヘッダファイルはありません。 > >> > #pragma hdrstop これは、何でしょ？ >> >> えっ、、 > >このプラグマは、プリコンパイル済みヘッダファイルを作成／使用するときに、 >ここまでプリコンパイルする(されている)ことをコンパイラに知らせるための >ものです。 > >プリコンパイル済みヘッダファイルとは、ヘッダファイルを途中まで >コンパイルした中間コードのダンプファイルです。 >これを作成して使用することにより、何度も同じヘッダファイルを >コンパイルするのに対して、コンパイル時間を大幅に短縮することが >可能になります。 > >VBにはそのような機能は無いので、移植の際に気にする必要は無いでしょう。 > >> >-------------------------------------------- >> >3) >> > >> > LPSTR findFile(const char *filename) LPSTRとは？ >> >> LPSTR?なんだっけ？そんなのあった？ >> if(!(chk_str = findFile(argv[1]))) >> でやってるから、 >> リターンでLPSTR型を返している？ >> chk_strの型宣言、見てください。 > >LPSTRはwindows.hで定義されている型です。char *(16ビットなら >char __far *)のtypedefです。 > >> >-------------------------------------------- >> >4) >> > >> > va = strtol(sa, 0, 16); この関数は、なに？ >> >> strtol?知らないなぁ、、 >> 予想ですが、文字列をＬｏｎｇ型にしているとか、、、 >> でも、それなら、ａｔｏｌがあるしなぁ、、 >> strtolって、関数、自作されてないか（標準関数以外？）みてください。 >> また、Ｖａの型宣言や、使われているところから、判断？ >> ｓａの変数は？0，16って？ >> 16進の文字列を直しているとか？ > >atolは10進数のみ変換可能です。strtolは16進数なども変換可能です。 > >> > CharToOem(str, s); もしかして、Winの関数？ >> >> これも、、、わからない、、、 >> またまた、予想？ >> 文字列の連結とか置き換えとか、、自作関数では？ > >WindowsAPI関数です。OEM定義の文字列に変換します。 > >それでは、メルマガ頑張って下さい。 strtol,CharToOem、、、あれ、標準関数だったのね、、 てっきり、自作関数かなぁ？なんて書いちゃって、 また、無知がバレちゃったけど、まぁ、Ｋｅｎ３らしくっていいかな？
ここまで、読んでいただきどうもです。ここから下は、三流君のホームページの紹介・案内です
目的の情報が見つかったか？少々心配しつつ、、、
項目別に本音？それとも建て前？的な記事をまとめました。
|
気になったジャンル↓を選択してください。 |
Blogとリンク:[三流君の作業日記]/ [愚痴(Bookmark)]/ [広告Blog(Bookmark)]