Robert Feldt <feldt / ce.chalmers.se> writes:

> Any ideas on higher-level things such as:
> * Division of modules/classes into files
> * Packaging modules and classes together

I find it sometimes hard to break Java habits here, but I'd guess the
basic rules are:

1. Each chunk of separately usable stuff goes in a separate file.

2. When not used as Mixins, modules are great ways of partitioning the 
   namespace. It can be a good idea to put your classes inside modules 
   for that reason. In general, avoid cluttering up the top level
   (there are enough names up there already!)

3. If there are groups of interrelated classes, stick them in the same 
   file (and possibly within a module in that file). This is
   particularly true of a main class and a set of helper classes.

4. Remember the layout of the files in directories doesn't have to
   mirror the logical partitioning of stuff into classes and modules.

Have a look at the lib/net stuff for some good ideas here.

> * Commenting (Are there several formats out there? Two tools in RAA)
> * etc

Ruby has #_to_end_of_line comments, and =begin/=end block
comments. The latter can be interpreted by rdtool. RDTool comes with a
pretty good English-language manual. (There's also an appendix on
rdtool in the book, but that doesn't help you much ;-) I find I use
fewer comments in Ruby, as the code is closer to the application
domain. 

When you first start using RDTool, you find yourself wishing it were
more like JavaDoc or DOC++. However, after a while you realize that
those style of tools don't work well in a language such as Ruby where
you can add methods and classes at runtime.

> BTW: Congratulations to your great book "Pragmatic Programmer". I've
> been teaching a process-oriented SE course for some years and been
> looking for a complementary and hands-on book with lots of practical
> advice; your book seems to be spot on! Hope to include it in next
> years course.

Thank you. If you want to pursue this, drop me a private e-mail and
I'll put you in touch with AWL.

> Any news on your Ruby book? When can we expect it?

It's getting there. We've got a rough first draft which is currently
being sanity checked. Once those comments come back (and assuming we
haven't totally ballsed it up) we'll make changes and go out for
formal review. That takes 3 to four weeks. By this time, we hope that
1.6 has been feature-frozen. We then make the changes (which takes
longer than you'd think) and get the indexing done (which
takes way, way longer than you'd think). We then send the Postscript
of to AWL. The books appear 6-8 weeks after that. So, I'm guessing
we'll see it in late September or October. In the meantime, once
things settle down we'll be putting extracts up on the web site.


Regards


Dave