- PR -

javadocの書き方について

1
投稿者投稿内容
Samiadon
会議室デビュー日: 2003/10/08
投稿数: 16
お住まい・勤務地: 東京都神戸市浪速区猿猴橋町三条下ル
投稿日時: 2004-01-08 21:03
コメント中にて文字実体参照を使用する場合、
javadocにしたときとソースを読むときの、どちらを
優先した表記にすべきなのでしょうか。

あまり良い例ではないかもしれませんが、ソースで見た時に

* "&"が来たら "&"に変換する
と、
* "&"が来たら "&"に変換する

の、どちらがいいのかといったレベルの話です。
t-wata
大ベテラン
会議室デビュー日: 2002/07/12
投稿数: 209
お住まい・勤務地: 東京
投稿日時: 2004-01-08 23:21
> javadocにしたときとソースを読むときの、どちらを
> 優先した表記にすべきなのでしょうか。

Javadocでしょう。
javaodcはHTMLのタグが入ったりするので、ソースで見るのにははじめから向いてません。

> * "&"が来たら "&"に変換する
> と、
> * "&"が来たら "&"に変換する

ソースで見たときにわかりやすいのは前者で、Javadocで見たときにわかりやすいのが後者だから迷っているのでしょうか？
不安なら、ソースで見たときにわかりやすいようにJavadocじゃない普通のコメントを追記しておけばいいんじゃないでしょうか。
unibon
ぬし
会議室デビュー日: 2002/08/22
投稿数: 1532
お住まい・勤務地: 美人谷　　　　　　　　良回答(20pt)
投稿日時: 2004-01-09 08:05
unibon です。こんにちわ。

引用:

Samiadonさんの書き込み (2004-01-08 21:03) より:
あまり良い例ではないかもしれませんが、ソースで見た時に

* "&"が来たら "&"に変換する
と、
* "&"が来たら "&"に変換する

の、どちらがいいのかといったレベルの話です。

どっちでもいいと言ってしまえばそれまでですが、拘るとすれば、ソースファイルを見ることが多いか、javadoc の HTML を見ることが多いか、が分かれ目かもしれません。
ちなみに、私はソースコード中の javadoc コメントは見ますが、HTML になったものは見ません。主観になりますが、あんな無駄に整形されたものを見てもしかたがないと思います。
といっても、人に見せる(あるいは見せてもらう)場合に、ソースコードを隠蔽されて、クラスファイルと javadoc の HTML のセットで渡す(あるいは渡される)ときは、もとのソースコードがないわけですから、そういう場合は javadoc の HTML に重きを置いても良いかもしれません。
あと、Eclipse の色付けはエンコーディングしてないと、色付けが多少おかしくなったかもしれません。
matobaa
常連さん
会議室デビュー日: 2002/12/26
投稿数: 21
投稿日時: 2004-01-09 10:26
JavaDocはHTML形式だけを対象としたものではないですから、HTML前提で考えるのはそもそも間違いだと思っています。
現状はほとんどのケースでHTML形式だ、という主張も否定しませんし、そう考えるなら、HTMLで見たときにきちんと読めるようにすればいいです。
権兵衛
ベテラン
会議室デビュー日: 2002/09/24
投稿数: 50
投稿日時: 2004-01-10 17:53
日本語環境限定になってしまうという問題はありますが、私は全角で記述するようにしています。
これだとソースでも出力したJavaDocでも同じに見えます。
1

スキルアップ／キャリアアップ（JOB@IT）