タブ区切りのCSV？

「カンマ区切りの CSV」などという言葉を聞くことがある。しかし、「CSV」は Comma Separated Values の略なので、それだけで「カンマで区切られた値」を意味する。更に「カンマ区切りの」とするのは冗長だろう。

同様に、「タブ区切りの CSV」と言う人がいる。

　"001,002,003" + "\t" + "abc,def,ghi" + "\t" + "あ,い,う"

こんなデータを意味しているのかと思えば、そんなこともない（\t はタブ）。

会話で聞くだけなら、意味を汲み取ることはできる。しかし、ソースコード上で、「タブ区切りのファイルを読み込む関数」の名前を「readCsvFile()」などとされると、「カンマ区切りのファイルを読み込む関数」だと誤解してしまう。

「タブ区切りのデータ」は、「TSV: Tab Separated Values」と呼ぶのが正しい。無用な誤解を避けるためにも、こうした用語は正しく使うようにしたいものだ。

応援のクリックお願いします →

---

■関連記事
・e-Words 「タブ区切り　【TSV】 」

---

2007-'08年版 [最新] パソコン用語事典

posted with amazlet on 06.10.29

大島 邦夫 堀本 勝久
技術評論社

Amazon.co.jp で詳細を見る

ファイルフォーマット便利帳―マルチメディア操作の必須知識を絵解き

posted with amazlet on 06.10.29

東 陽一
CQ出版
売り上げランキング: 176,011

おすすめ度の平均:

ソフトウェア関連の開発者などにお勧め。

Amazon.co.jp で詳細を見る

もっとコメント論 ～その５～ コードが求めるコメント

コメントは英語で書くべき？

プログラミングのコメントについて、何が何でも英語で書かなければならないと主張する人がいるらしい。

確かに、日本語は、環境によっては入力できないとか、正しく表示できないといった問題が起こる場合がある。しかし、少なくとも仕事で開発を行う場合には、そのような状況はほとんど考慮する必要はないだろう。

このような文字コード上の問題の他に、どうしても英語でなければならないという積極的な理由が何かあるだろうか？

ソースコードは読者に情報を伝えるための手段（メディア）である。

どんなメディアでも、情報の受け手が誰なのかということを想定するはずだ。そして、その時点で、どんな言葉や表現で伝えるべきかということは自ずと決まる。

ソースコードも例外ではない。「読者層」を想定し、その読者に最も適した言葉でコメントを書くべきだ。結果、英語になることもあれば、日本語になることもあるだろう（※）。

読者の立場に立つ

良いコメントとは、「読者が求めるコメント」である。コメントに限らず、ソースコード上手く書こうと思えば、常に読者の存在を意識し、読者の立場に立つことが必要だ。そのためには、まず、自分自身が読者としての経験を積むことが必要である。

しかし、その経験が不足しているプログラマは意外に多いようだ。特に、「直す不幸、直せない不幸 」で述べたような「作り逃げ」の仕事ばかり続けていると、実務の中で、他人の書いたソースコードを読むという機会がなかなか得られない。

仕事でプログラマをやっていれば、周りには、他人の書いたソースコードが少なからずあるだろう。自分の作業に直接関係ないものであっても、積極的に読んでみるのもよいのではないだろうか。

コードが求めるコメント

ここまで、コメントについて長々と書いてきたが、ソースコードの主役は、あくまでもコード本体（プログラミング言語で書かれた部分）であることは忘れてはいけない。

まず、コメントを上手く書く以前に、コード自体を上手く書く必要があるのは、言うまでもない。決して、読みにくいコードをコメントで誤魔化すようなことがあってはならない。

そして、コメントはコードを生かすために書くべきである。良いコメントは、コードとマッチしていて、コードの邪魔をしたりしない。これは、つまり、コードの書き方によって、コメントの書き方が変わるということでもある。そういった意味では、「コードが求めるコメント」を書くべき、という言い方も出来るだろう。

例えば、プログラミング言語の特性によって、コメントの書き方は変わってくる。「バッチファイル」のような構造化しにくい言語と、Java のような例外処理まで備えたオブジェクト指向言語では、コードの書き方が全く違う。当然、コメントの書き方も違うものになるはずだ。

最後に

プログラミングにおいて、コメントをどう書くかということは、重要な問題だ。にもかかわらず、プログラミングの入門書や、企業の研修では、それほど重視されていないようである（他に学ぶべきことが多すぎるのだ）。プログラマは、良いコメントとはどのようなものかを、一度、自分で考えてみる必要がある。

そして、プログラミングを行う際には、より良いコメントを書くことを常に意識すべきだろう。例えば、自分のコードを見直すときには、コメントの書き方まで注意してみる。それだけでも、ずいぶん違ってくるのではないだろうか。

応援のクリックお願いします →

---

※簡単に言えば、日本人ばかりのプロジェクトでは日本語で書くべきだ。ただ、コード中のクラス名や関数名、変数名などに「英単語」を使うべきか、日本語の「ローマ字表記」を使うべきかという選択は、そう簡単ではないだろう。

---

■関連記事
・もっとコメント論　～その１～　コメントとは何か
・もっとコメント論　～その２～　見出しとしてのコメント
・もっとコメント論　～その３～　注釈としてのコメント
・もっとコメント論　～その４～　システムの開発や保守のために

---

ロジカル・ライティング

posted with amazlet on 06.04.30

照屋 華子
東洋経済新報社 (2006/03/24)

Amazon.co.jp で詳細を見る

CODE コードから見たコンピュータのからくり

posted with amazlet on 06.04.30

Charles Petzold 永山 操
日経BPソフトプレス (2003/04/10)
売り上げランキング: 61,374

おすすめ度の平均:

いい日本語に訳してほしい
コンピュータのからくりが手に取るようにわかる
目からうろこが落ちるかも？

Amazon.co.jp で詳細を見る

ecotonoha

"IT" の TBステーション、今週のテーマは「おすすめスクリーンセーバー 」だったようだ。しかし、ずいぶんと記事が少ない（システムの調子が悪いのかな？）。

このブログのテーマとは直接関係ないが、地球のために、ecotonoha を紹介しておこう。




詳しくは、バナーをクリック。

---

[PR] やさしく節約印刷
[PR] 印刷経費を節約するだけじゃない！
[PR] 今日からはじめるエコロジー

もっとコメント論 ～その４～ システムの開発や保守のために

これまで、「見出しとしてのコメント 」、「注釈としてのコメント 」について考えた。純粋にソースコードを完成させるという意味では、これらが上手く書ければ十分だろう。

ただし、システム開発という仕事の中では、更に、他の情報が求められる場合がある。そういった付加的なコメントの用途についても、いくつか書いておこうと思う。

ログとしてのコメント

ソースコードを変更した時、変更前のコードをコメントとして残しておくことがある。いわゆる「コメントアウト」である。

システムの保守をしていると、コードの変更履歴が知りたくなる場合がある（※１）。そのような事態を想定して、過去のコードを消さずに残しておくわけである。

このような場合、修正した日時や理由などを合わせて書いておけば、有益な情報となるだろう。いわば「ログとしてのコメント」である（※２）。

実は、この「コメントアウト」を残すことは、私はあまり好きではない。古いコードが残っていると、誤読の原因にもなるし、GREP（文字列検索）の邪魔にもなる。変更の履歴については、CVS や VSS などのソース管理用のソフトを使って管理したほうがよいだろう。

とはいえ、常にそういった管理ソフトが使えるわけでもなく、「ログとしてのコメント」を全面的に否定することもできない。

リンクとしてのコメント

ソースコードには、このようなコメントを見かけることがある。

　// [不具合票 No.00123] ××問題の修正

システムで発生したバグを、「不具合票」という書類で管理しているのだろう。コードの修正についての詳細な情報については、不具合票の No.00123 を参照せよ、というわけだ。

ここでは、書類の番号と、コードの修正箇所を「紐付ける」ために、コメントが利用されている。つまり、「リンクとしてのコメント」である。

このようなコメントも、システムの保守をする上で、有用な情報になる場合がある。過去の修正履歴を残すという意味では、「コメントアウト」と同じ用途といえるかもしれないが、「コメントアウト」ほど邪魔にはならないだろう。

覚え書きとしてのコメント

このようなコメントもある。

　// TODO: ××関数が完成したら、ここで呼び出すこと

「××関数」を呼び出す処理を書きたいのに、その関数がまだ出来ていないのだろう。後で書くのを忘れないように、メモしているのだ。

もちろん、こうした「TODO コメント」は、不要になったら消してしまうべきものだ。残っていたとしたら、「やるべきこと」をまだやっていないか、コメントを消し忘れているということになる。折をみて「TODO:」という文字を検索し、チェックすることも必要である（※３）。

多くの場合、「TODO コメント」の「読者」は自分自身なので、書き方については、それほど気にすることはないだろう。

★

ソースコードをひとつの完成した「製品」あるいは「作品」としてみた場合、今回挙げたようなコメントは、必要のないものだろう。あくまでも、システムの開発や保守といった、業務上の都合で付加するものである。

しかし、やはり、読者のために書くものだということには違いはない。読者が「修正前のコード」を必要とするからこそ、コメントアウトして残すのである。逆に必要とされていない場合は、残す必要はない。

続く

応援のクリックお願いします →

---

※１
「ログ」については、「ログとしてのメール 」も参照。

※２
例えば、「デグレ」の調査をするような場合である。デグレ（デグレード）とは、プログラムを変更（改良、修正）したために、それまでうまく動いていたものが動かなくなるようなこと。いわば、「プログラムの改悪」。

※３
Visual Studio .NET や Eclipse といった最近の開発環境では、こうした「TODOコメント」を一覧表示する機能があって、便利だ。

---

■関連記事
・もっとコメント論　～その１～　コメントとは何か
・もっとコメント論　～その２～　見出しとしてのコメント
・もっとコメント論　～その３～　注釈としてのコメント
・もっとコメント論　～その５～　コードが求めるコメント

---

保守とリエンジニアリング―アーキテクチャとドメイン指向トラック

posted with amazlet on 06.04.30

上原 三八 佐野 隆 Wei‐Tek Tsai 馬場 一弥
共立出版 (2000/12)
売り上げランキング: 330,491

Amazon.co.jp で詳細を見る

Microsoft Visual Source Safe 6.0

posted with amazlet on 06.04.30

マイクロソフト (1998/10/23)
売り上げランキング: 10,845

Amazon.co.jp で詳細を見る

もっとコメント論 ～その３～ 注釈としてのコメント

私が書いて欲しいと思うコメントとして、前回 は「見出しとしてのコメント」について述べた。今回は、もうひとつ、「注釈としてのコメント」について書いておこうと思う。

注釈とは

そもそも「注釈」は「comment」の訳語のひとつであり、「ソースコードのコメント」としても、最も一般的な用途でもあるだろう。

「Yahoo!辞書 - 大辞泉 」によると、注釈とは「語句の意味や用法を解説したり、補足的な説明を加えたりすること。また、その説明。」である。ソースコードに書く場合にも、本質的な違いはないだろう。

注釈を書く目的は、読者の理解を助け、誤解のないようにすることである。まず、プログラマは、このことを忘れてはならない。

過不足なく書く

「注釈としてのコメント」を書く上で最も注意すべきは、過不足なく書くということだ。

必要なコメントを書かなければ、コードが「何をしたいのか」ということを読者に伝えることができない。逆に、無用なコメントを書けば、コードが読みにくくなるし、将来的に「嘘（コードと不一致）」になる可能性も高くなる。

コメントを書く時には、常に、「もっと必要なコメントがあるのではないか」とか、「今書いているコメントは本当に必要なのか」ということを、読者の立場に立って、よく考えなければならないだろう。

コードで表現できないことを書く

「その１ 」で書いたように、無用なコメントを書きすぎる人は多い。そして、そのことが、コメントは書くべきでない（書かなくても済むのなら、それが理想だ）といった、コメント無用論を生んでいるように思う。

コメント無用論の核となっているのは、「コードを読めば分かることをコメントに書く必要はない」という主張である。それ自体は正しいだろう。しかし、それは裏を返せば、「コードを読んでも分からないことは、コメントに書くしかない」ということでもある。

例えば、

　// CR + LF を LF に置換
　data = data.replaceAll("\r\n", "\n");

これは不要なコメントだ。「コードを読めば分かること」しか書かれていないからだ。

では、次のようなコメントはどうだろう。

　// Windows 98 では化けるので（Me/2000/XPでは化けない）
　data = data.replaceAll("\r\n", "\n");

「コードを読んでも分からないこと」が書いてある。つまり、もし、このコメントを削除したら、その情報は欠如してしまうということである（※２）。

コメントには「HOW」ではなく「WHY」を書けと言われるが、このような例は、それを端的に示している。HOW（どのように処理しているか）は、コードそのものから読み取ることが出来る。しかし、WHY（なぜそのような処理をしているのか）は、コードからは読み取れない。

読者に伝えたいこと、伝えるべきことがあっても、プログラミング言語だけでは表現できない。そういうときに、注釈としてコメントに書く。当り前といえば当り前のことである。

どう書くか

「HOW ではなく WHY を書く」という考え方は、「注釈としてのコメント」を書く上での枠組みを示してくれる。

しかし、それだけで上手く書けるようになるわけでもない。言葉の選び方、文章の書き方など、悩みながら書くことになる。ここでも、文書作成の能力が問われるところである。

続く

応援のクリックお願いします →

---

※１
注釈をどこまで書くかということは、あくまでも読者の立場で考えるべきである。例えば、読者がそのシステムの設計や仕様をどの程度理解しているのか、技術的なスキルがどの程度なのか、といったことが関係するだろう。チーム開発では、チームの他のメンバーを読者として想定するといいだろう。読者が不特定多数の場合であっても、どこかに「読者層」を想定しなければ、コメントの細かさの点で、一貫性がなくなってしまうだろう。

※２
トラックバックでも指摘されているが、以前は、この部分に、不適切な例（WHY になっていない例）を記載していた。この記事を新しく読んでくださる方のために本文を修正し、修正前の内容は以下に残すことにした（2005/09/10）。

例えば、

　// システムプロパティの "swing.noxp" に "true" を設定する。
　System.setProperty("swing.noxp", "true");

これは不要なコメントだ。「コードを読めば分かること」しか書かれていないからだ。

では、このコメントは消してしまえばよいのだろうか？

これは Java のソースコードである。しかし、Java プログラマの中にも「コードを読んでも何をしているのか分からない」という人は多いのではないだろうか。少なくとも自分がそのように判断するのであれば、「注釈としてのコメント」を書くべきだろう（※１）。

同じコードでも、次のようなコメントが付いていればどうだろう。

　// Windows XP でも、従来風のデザインで画面を表示する。
　System.setProperty("swing.noxp", "true");

これなら、そのコードが「何をしたいのか」ということがよく分かるのではないだろうか。

---

■関連記事
・もっとコメント論　～その１～　コメントとは何か
・もっとコメント論　～その２～　見出しとしてのコメント
・もっとコメント論　～その４～　システムの開発や保守のために
・もっとコメント論　～その５～　コードが求めるコメント

---

「分かりやすい文章」の技術

posted with amazlet on 06.04.30

藤沢 晃治
講談社 (2004/05/21)
売り上げランキング: 1,915

おすすめ度の平均:

本当に「わかりやすい」です
相手の立場に立った分かりやすい文章
1冊だけでも十分

Amazon.co.jp で詳細を見る

プログラミングテクニック―UNIXコマンドのソースコードにみる実践プログラミング手法

posted with amazlet on 06.04.30

多治見 寿和
アスキー (2003/11)
売り上げランキング: 10,396

おすすめ度の平均:

ハッカーになる入門書
本当のプログラマになるためには

Amazon.co.jp で詳細を見る