Toshです。

In message "[ruby-list:23234] Re: readablity of RD"
    on 00/06/14, TAKAHASHI Masayoshi <maki / inac.co.jp> writes:
>> こんなんじゃダメ？
>> begin と end の組がうざいかも・・・
>> 
>> =begin
>> = 大見出し
>> あいうえお
>> かきくけこ
>> =end ############################################################
>> =begin
>> = 大見出しその2
>> ここだよ〜〜〜〜〜〜
>> =end
>
>うーん、でも、まさに「begin と end の組がうざい」というのがあると
>思います。つまり、
>
>   ・見出しと「=begin」「=end」のマークアップがそっくり
>
>であるのが見出しを目立たなくさせる要因の一つじゃないかな、と。

うむうむ、なるほど。

>これはクラスやメソッド中などに細かくRDを入れるスタイルに顕著で、例えば
>
># RDtool-0.6.3より
>-----------------------------------------------------------------
>      end # catch
>    end # apply_to_Include
>  end # RDVisitor
>
>=begin
>== module AutoLabel
>this module provide automatical labeling feature to Visitors.
>=end  
>  module AutoLabel
>
>=begin
>  --- AutoLabel#prepare_labels(tree[, prefix])
>        initialize method. call it before calling (({((<AutoLabel#refer>))}))
>        ((|tree|)) is (({RDTree})), and ((|prefix|)) is a (({String})) which
>-----------------------------------------------------------------
>
>こういうのをぱっと見ても、RD的にAutoLabelの見出しに気づきにくいのです。

そもそも、Emacs + ruby-modeで書いている時には色が違うのでどこがRDなの
かすぐわかるのですが、そうでない時はRDとスクリプトの境界は見えづらい
という問題もあります。

僕はどうしようもないか、とも思ってますが。

上の例で提案してみた形式を使ってみると・・・

  =begin
  == module AutoLabel =======
  this module provide automatical labeling feature to Visitors.
  =end  
    module AutoLabel

  =begin
  ...

結構いいかも。

># あ、どこからどこまでがコメントなのか分かりにくいというのもあるか。
># なお、自分で書く時はRDは前か後ろにまとめて書きます。

でもこの書き方なかなか便利なのですよ。最近はメソッドを書く時には
対応するMethodListをとりあえず書いてしまう、というような書き方を
しています。説明文は面倒なら省略してしまってもよくて、これだけでも
自分の定義したクラスのMethod一覧がHTMLですぐに出せるので、引数の
順番とかを忘れた時、とかになかなか便利なのです。

---
Tosh
Toshiro Kuwabara