[seasar-javadoc:101] Re: ツッコミ大歓迎! 叩き台サンプル

2006年 5月 30日 (火) 01:42:45 JST

鈴木(belltree)です。

はじめまして、ももたろさん。
指摘ありがとうございます! (mOm)

【恥の】説明(言い訳？)をさせて下さい【上塗り】^^;;;

・１行の長さ
> * ある程度で改行を入れてもらった方が、読みやすいかと思います。
ですよね…。実は、手書きの段階では、各行を適切な(と思う)長さで
揃えたのですが、Ctrl+Shift+F したらこんなん出ました。(^^;;;;
※ 説明入れておけば良かったですね。
eclipseのフォーマット定義を変えれば直るんでしょうか？(未調査)
動きを見ていると、１行の最大長の設定が長めのような雰囲気です。

・半角文字列の前後の空白
> * 半角文字の前後の空白は入れないルールだと思います。
>   何箇所か、<code>の前に空白があるようでした。
これも上の話と関連するのですが、手書きの段階では、空白は入れて
ませんでした。この状態で Ctrl+Shift+F したら、添付したファイル
よりも１行の最大長がより長くなってしまいました。
私の予想ですが、英語で書く場合には、半角スペースが単語の区切り
になるので、そこで改行されるのですが、日本語の場合には、区切り
がなく、「、」「。」も区切りと解釈されないのだと思います。
苦肉の策として、『このあたりで改行して欲しいなぁ』という場所に
半角スペースを入れて Ctrl+Shift+F した訳です。
でも、このやり方は本末転倒で、自分でもイケテナイと思います。
(解決策模索中…)
それから、"半角文字"の前後"全て"に空白を入れたのは、実際
Javadocを生成してみたら、半角文字の前後が詰まってしまって、
私の感覚からは、見づらかったので入れてしまいました。
でも、よく考えれば、この辺はフォントにも依存しますし、空白を
入れるという、余計な気を使う必要もないと思うので、『空白なし』
に賛成です。
…というかルール([seasar-javadoc:17] Re: ガイドライン)でしたね…
記述中はWikiしか見ていませんでした(^^;;;;;

・負荷分散
Javadoc Wiki に記載されていないルールの追加などは、気づいた人が
Wikiに書いてから、このMLに『Wikiにこんなの書きました』メールを
流すようにすれば、【見覚え】koichik【あります】さんの負荷が減る
かなぁと思うのですが、皆さんいかがでしょう？
※ Javadoc Wiki は気軽に書き加えても良さそうな雰囲気ですし。

・閉じタグ
> * <p>を段落区切り文字として使うのはあまりよくなさそうです。
>   段落を<p>～</p>で囲った方がHTMLとしてはよいのではないでしょうか。
Javadoc Wiki の方針に『HTML 4.01 Transitional を想定』と書いて
あったので、閉じタグ省いちゃいました。
確かに、今後XHTMLで出したいと思った時に修正する手間が少なくて
済むし、閉じタグがあった方が落ち着くかも。

> * 何箇所か、リテラルだと思われる部分が<code>で囲んでいませんでした。
>   > ...Beanプロパティ(getter/setter)によるアクセスを表します。...
>   の「Bean」「getter」「setter」あたりでしょうか。
リテラルという言葉は、普段何気なく使っているのですが、この文章を
書こうとした時に、自分の頭の中の「リテラル」と世間一般の「リテラル」
ってズレてない？と思い、IT用語辞書のサイト(※)で確認してみた所
※ http://e-words.jp/w/E383AAE38386E383A9E383AB.html

▼-----------------------------------------------------------
リテラル　【literal】
読み方 ：  リテラル 
　プログラムのソースコード中に使用される定数のこと。「255」「fujiyama」
など、いわゆる単なる数字や文字列がリテラルの代表例である。
プログラミング言語は、リテラルの型を確実に判別するために(文字が書いて
あるときは文字列か変数か区別する必要もある)、コード中にリテラルを指定する
ときに特定の書式を要求する。例えば、文字列を表記する際は必ず前後を「"」で
括る、と定めている処理系が多い。このため、プログラミングに関する文章では
必要に応じてリテラルを型ごとに分類し、「数値リテラル」「日付リテラル」など
と呼び分けるのが一般的である。対義語は「変数」。
-----------------------------------------------------------▲

と書いてありました。ズレてました。まあ、文脈によって単語の意味は
変わるので、辞書の意味が必ずしも正確な意味を示すとは限りませんが、
この意味を採用した上で文章を考えてしまいました。

ここも「実は…」シリーズなのですが、元々は、
Beanの所も、getter/setterの所も<code></code>で括っていました。
それがなぜああなったかといいますと…
1. <code>Bean</code>、<code>getter</code>、<code>setter</code>
   >>> 「リテラル」をIT辞書で引く
   >>> フム、ってことはリテラルではないな
3. Bean、getter、setter
   >>> これらの文字列って一般名詞では？日本語の方がいいか
2. ビーン、ゲッター、セッター
   >>> なんか見た目上しっくりこない(以前はこう書いたことも…)
3. Bean、getter、setter
   >>> 自分、これ以上いい書き方が浮かばないっス
と、まあこうゆう訳です。(^^;;;

ついさっき、「THE Elements of Java Style」を見てみたのですが、
その中の<code></code>に関する規約は次のようになっていました。

▼-----------------------------------------------------------
規約43. 
キーワード(keywords)、識別子(identifiers)、定数(constants)を
<code>...</code>タグで囲む。

/**
 * 引数<code>value<code>が示す<code>Flag</code>オブジェクトを
 * 生成します。
 * ...
 */
public Flag(boolean value) {...}

<code>...</code>タグで囲んだ部分は、HTMLブラウザで表示した際、
通常のテキストと異なるスタイルで描画されるため目立ちます。
-----------------------------------------------------------▲
[超☆意訳]

識別子と定数については、迷いませんが、「キーワード」は、
ちょっと完全には規約化できなさそうですね。

P.S.
ひょっとして、私、プロジェクトを本筋から逸らせてません？
逸らせてたら遠慮なく言って下さい。
「細かいこと気にせず、とりあえずやりゃぁいいんだYo!」とか (^^;;;

P.S.2
今見たらレスがいっぱい増えている!…ありがとうございます。
これから読みます。

/** 
 * @auther Hideaki Suzuki
 * @contact suzuki at uinet.or.jp
 */