nDiki : ドキュメンテーションコメント

ドキュメンテーションコメント - documentation comments

プログラムのソースコード中にドキュメンテーションを目的として決められた形式で書かれるコメントのこと。

ツールによりドキュメントファイルを生成するのに利用されたり、IDE におけるヘルプドキュメントに利用されたりする。

プログラミング言語 (プログラミング環境)と形式

言語(環境)形式書式特徴主なツール
PerlPodperldoc
RubyRD
Visual C++XML ドキュメント コメントVisual Studio cl.exe の /doc オプション。
Visual C#XML ドキュメント コメントXML ライクなタグで書く。Visual Studio
JavaDoc Comments@~ タグを使う。Javadoc

複数のプログラミング言語に対応したツール

文体

日本語版ドキュメントにおける文体は下記である。

スポンサード リンク

2009年10月6日 (火)

IDETo Do

ソースコードTo Do タスクを埋め込むのにどの形式が良さそげか調査。

Visual Studio 2005

トークンとして "TODO" が登録済み。 大文字小文字を区別する。 コメントの先頭に TODO がある必要がある。 この設定の時に @TODO と書いても認識しない。

トークンには @ 文字を設定できない。

Eclipse

テキストとして "TODO" が登録済み。 大文字小文字を区別する。 コメントの先頭でなくても良い。

この設定の時に @TODO と書いても認識しない。

Doxygen

IDE じゃないけど。 ドキュメンテーションコメント中に \todo または @todo。 \TODO や @TODO は駄目。

ということで

コメントの先頭に TODO を書くという書式で統一しておくのが良さそげ。

Visual Studio 2005 がコメントの先頭以外でも認識してくれるのなら

  /** @todo TODO 説明 */

としておけば、ちょっと冗長だけれど doxygen にも認識させられるのなあと思ったり。

スポンサード リンク
[ 10月6日全て ]

2011年2月1日 (火)

今日のさえずり: 昔は例外処理を好んで使っていたが、最近はできるだけ使いたくない派

2011年02月01日

  • 08:05 明日 9:15 で病院予約した。花粉症もらいにいく。
  • 09:31 Wi-Fi に対応したspモードメールアップデート中。 #Xperia
  • 09:37 完了。Wi-Fi 設定はあ・と・で。 #Xperia
  • 09:59 GPS での測位、今日は東にだいぶずれてるな。端末の問題? #Xperia
  • 10:05 あ、良くなってきた。
  • 10:45 プリンタ保守のエンジニアから電話修理難航中でまだしばらくかかりそうとのこと。いったいどんな不具合だったんだろう。
  • 11:59 Google アカウント1つ潰した。
  • 12:07 弁当 350円。 (@ 向日葵 和泉町店・カレー食堂) http://4sq.com/eLgExR
  • 12:18 「40前後で『ガールズトーク』と言うのはいかがなものか」ってにいったら、いいんだって言われた。「セックス・アンド・ザ・シティ」が何たらとか説明された。ということでアリらしいです。
  • 13:32 REGZA Phone T-01C 買った同僚に K-9 Mail 薦めた。 #Android
  • 13:33 Google アカウントもう1つ潰した。
  • 17:07 spモードメール、バックグラウンドで送信できるようになったんだ。これは大きな進歩。 #Android
  • 18:52 コーディング規約内の心得に「サンプルを鵜呑みにしない」と書いてあるのだが、その後コーディング規約内にサンプルが出てくるので心がザワザワする。
  • 19:01 昔は例外処理を好んで使っていたが、最近はできるだけ使いたくない派。
  • 19:09 @wtnabe 開発が進むにつれて、どんな例外が throw されてくるかが次第に自明で無くなってくるから。
  • 19:16 @gnue 開発が進むにつれて、どんな例外が throw されてくるかが次第に自明で無くなってくるから。
  • 19:21 Joel Spolsky の「間違ったコードは間違って見えるようにする」に例外処理について書かれているけど、だいたいその主張に近い。
  • 19:24 Google C++スタイルガイドも C++ の例外を使わない派。
  • 19:27 More Joel on Software に収録されてる。 http://amzn.to/eARt3t RT @Naney: Joel Spolsky の「間違ったコードは間違って見えるようにする」に例外処理について書かれているけど、だいたいその主張に近い。More Joel on Software
  • 19:36 呼び出し先を全部辿らないとどんな時に何が throw されてくるかわからないし、ここで throw するようにすると全ての呼び出し元できちんと catch されるのかも全部辿らないといけない。
  • 19:42 ドキュメンテーションコメントにおいてメソッドが何を throw するかってのも最初は書いてみるけど破綻するよね。
  • 20:18 K-9 MailGmail からプッシュするフォルダを INBOX フォルダから重要フォルダに変えてみた。優先トレイがきちんと学習してくれれば、ちょっとしたニュースレターとかでの通知が減るはず。 #Android
  • 20:20 INBOX の同期間隔は長めに変更。 #Android
  • 21:52 spモードパスワードって何だ。
  • 21:53 わかった。あれだ。
  • 22:03 Wi-Fi 接続でのspモードメールの送受信を確認。 #Xperia
  • 22:24 先週の水曜日に爪が折れていて皆が困っていた(と思われる) LAN コネクタを直したんだけれども、誰も「いいね!」って言ってきません。計算機管理チームとはそういうものです。
  • 24:25 X-Face 懐かしい。Sylpheed だと今でもちゃんと表示されるんだ。
[ 2月1日全て ]

2011年2月2日 (水)

例外処理機構は刃物だ

More Joel on Software

昔は例外処理機構(try で catch で throw、throw)を好んで使って設計・実装していたが、最近はできれば使わない方がいいかなと思っている。 あれは刃物だ。気違いに刃物だ。宇宙戦艦ヤマトだ。

全体が見渡せるか管理下における規模のプログラムでは有効だが、そうではない場合はあれはヤバイ。面倒。そして落ちる。

Joel Spolsky の More Joel on Software「間違ったコードは間違って見えるようにする」に例外処理について書かれているけど、理由としてはだいたいその主張に近い。

Google C++スタイルガイドも C++例外処理機構を使わないとしている。

呼び出し先から一体何が throw されてくるのか?

呼び出し先ツリーを全部辿らないとどんな時に何が throw されてくるかわからない。

ドキュメンテーションコメントにおいてメソッドが何を throw するか説明されているからそれを見ればいい? それって信用できる? 自分は今書いているメソッドの呼び出し先で throw される可能性のある例外とメソッドで throw する可能性のある例外を、そのメソッドのドキュメンテーションコメントに毎回きちんと書いてる? コードの変更を反映させてる?

え? throws clause?

呼び出し元できちんと catch してくれるの?

今書いているメソッドで、例外を throw したくなった。 でもこれってきちんと catch されるの? 呼び出し元ツリーを全て確認して、必要があれば catch を追加しなければならない。さもなけらば……落ちるよね。

え? とりあえず全ての型を catch して中の例外処理が空になっているそのブロック何?

ということで

例外処理機構を使うと、頻繁に深くコードをチェックしなければならなくなる。

いや便利だしスマートに書けるし、言語/ライブラリ的に使わざるを得ない時もあるし、使う時は使うけどね。

die;

[ 2月2日全て ]

About Me

Naney Naney (なにい)です。株式会社ミクシィでマネージャー・プロダクトオーナーをしています。

nDiki1999年1月に始めたコンピュータ日誌を前身とする NaneyWeb 日記(兼パーソナルナレッジベース)です。ちょっとしたノートは nNote にあります。

follow us in feedly

※内容は個人的見解であり所属組織とは関係ありません。

月別インデックス
Process Time: 0.147923s / load averages: 0.53, 0.51, 0.56
nDiki by WATANABE Yoshimasa (Naney, Google profile)
Powered by DiKicker