青木です。

On 2007/08/12, at 23:59, sheepman wrote:

> こんばんは、sheepman です。
>
> メソッドの説明中の例の位置に関してです。
>
> http://doc.loveruby.net/wiki/HowToWriteMethodEntry.html
>
> で、例は最後にまとめるということになっていることに最近気がつき 
> ました(笑)。
> これだと、例とそれを説明している文章が離れてしまいます。例の位 
> 置はもう少し
> 柔軟に対処しちゃいけないでしょうか。

> Ruby のリファレンスの場合は、例が割と多くて、個々の例の行数は 
> 短いので
> 説明の本文の間に入れてもおかしくないと思うのですが。どうでしょ 
> うか。

まず、ここで言及されている「例」はよく見ると二つのパターンがあると
思います。一つめは文章を補足する形で入れられている「コード例」、
二つめは単独で意味をなす「コード例」です。

eklerni さんが挙げている Class.new の例は前者にあたると思 
います。
それに対してわたしが「あとにまとめて書く」と書いたときに意図して
いたのは後者です。例えば String#* のような使いかたが該当し 
ます。

   String#* のマニュアル
   http://doc.loveruby.net/refm/api/view/method/String/i/=2a

でもって、前者のような、文章の途中で補足としてコードを使う方法
は非常に難しいです。なぜかというと、そのコード例がどういう位置
付けにあるのか明確にするのが難しいからです。

例えば Class.new の場合は直前にある「最初に名前を求める際 
に代入
されている……」というくだりを実例で示している、の  ** だ 
ろうなあ**
とはわかるんですが、明確に書いてあるわけではありません。直前の
段落に「以下にその例を示します」とかなんとか書いてあればちょっと
違ってくるでしょうが、いまの文章では舌足らずです。

それから、Class.new の二つめのコード例ではコード例を主語と 
して
使っていますが、これも非常によろしくありません。日本語の文の途中
にコードを入れるべきではありません。文の途中にコードを入れると
主語や目的語が巨大になって読みにくいからです。この場合なら次の
ようにすべきです。

   Class.new(super) {|m| ... } は以下のコードと同じです。
       ……コード……
   なお、ブロックの実行は Module#initialize が行います。

一般に、コードを入れながら説明すると、よろしくない書きかたに
つながりがちです。ですからわたしとしてはコードを途中に入れる
書きかたを推奨しません (ただし禁止はしません)。どう 
しても例が
ないとわかりにくい場合は、コード例がなんのために入っているのか
十分に説明を加えてください。


それから、最後にまとめて書くコード例は、主に使用例を書くために
使います。それに対して文章の途中で書くコード例は文章を補うため
に使います。目的が違う以上、どちらか一つに絞ることはできません。

さらに言えば、使用例は必須です。それに対して、説明のために使う
コードは必須ではありません。また、説明の途中で例を書いたから
使用例はいらないということにもなりません。


わたしの結論をまとめて書きます。

   1. 最後にまとめて書く例はそのメソッドの使用例である。
      getter メソッドみたいに使いかたが明らかすぎるものを除いて、
      使用例は常に付けるべき。1 行でもいいので付けるべき。

   2. メソッドの説明の補助として使うコード例は必ずしも必要でない。
      また、使うときはそのコード例がなんのためにそこに書いてある 
のか
      ちゃんと説明すべき。

--
青木峰郎

--
ML: ruby-reference-manual@m...
使い方: http://QuickML.com/