On Tue, 14 Mar 2006, Austin Ziegler wrote:

> Okay, Ara. Why do these methods need to be abstract and specifically have
> code around them? IMO, the *same* question should be asked of tsort.rb. I
> think that, in both cases, the answer is the same: they don't.
>
> Adding a definition for an "abstract_method" really doesn't add *anything*
> to the readability of the code that a well-written comment (which *is* read
> by rdoc without modification) doesn't provide.

you are perfectly correct.  however, i think we all know that there is a lot
of code, especially in-house, where the docs are pretty thin.  in my case
keeping 30,000 lines of ruby documented makes no sense since

   - i'm the only developer

   - we do research and the code changes daily

   - it's less work to use long variable names and abstract code at every
     possible opportunity into stand-alone libs than to write docs.

it just makes my life easier to do things like (all real examples)

   native_int_attribute 'samples'

   xdr_long_attribute 'grid_size'

   $LOAD_PATH << "nrtlib" # vs $:

   abort "#{ $PROGRAM_NAME } parse failure" # vs $0

   hash_of_subscriber_to_prefixes = {}

   abstract_method 'foo'

   required_argument 'dirname'

   option '--verbose', '-v'

in otherwords, to make the code slightly more verbose, self describing, editor
searchable (this is huge ihmho), and clear to someone new taking over the
project because there aint' any docs.

also, i'd maintain encoding sematics into docs is more difficult that it
sounds.  if it weren't the entire stdlib would have great docs - lord knows
there has been enough time and man power available.  but the truth is in the
puddin - people (myself included) don't do it (enough).

> I'm not sure. As I said earlier, PDF::Writer doesn't use them. In
> development versions of PDF::Writer, things like that have appeared -- and
> promptly been removed because they add clutter, not clarity.

trust me - i with you.  sometimes.  most of my libs take that approach too.
but sometimes it's nice to be extra clear.

the thing is, having 'abstract_method' does not prevent one from using your
approach - it's simply another arrow in the quiver.

> I ask, instead, how old tsort.rb is -- and that will generally indicate why
> it has defined abstract methods.

sure.  but it's in the stdlib as is alot of old code where often the code is
the only correct/detailed documentation.  i don't even use ri or rdoc anymore
- i prefer to simply do something like

   vim -o webrick.rb webrick/*

and peek around.  it would be great to then do

   /abstract_method

just as i know often do

   /attr

or

   /def <<

etc.

> Ara, this ignores the examples I gave early on:
>
>  # All clients of this module must implement #each with no parameters.
>  module Enum
>    def map
>      arr = []
>      each { |elem| arr << yield(elem) }
>      arr
>    end
>  end
>
> I have just made #each an abstract method without adding any code at
> all.

oh i know, and i'd never use 'abstract_method' here - but what if the number
of 'virtual abstract methods' exceeded fifty?

> And I disagree that it makes it easier to read, Ara. I don't write
> 10,000 line programs,

(OT: me neither btw - but all the libs/progs together approach 30k in my
latest system - i think the largest __file__ is only about 1000 lines.  fyi)

> but PDF::Writer is 5,000 lines. Certain items, especially in current
> development versions, could *easily* have been declared as "abstract" (and
> would have to had been in static languages) but aren't necessary to do such
> in Ruby.

> I really don't think that there's need for this in the core. I think
> that the use of it is a crutch; with the programs you have to write,
> Ara, that might be necessary. (I've used similar crutches in some
> versions of PDF::Writer experiments.)

you may be right here - perhaps a lib only.  still, one could make almost
every argument against 'attr' and co. you've made against 'abstract_method'.
both are unnecessary simple convenience solutions for simple problems.  still,
unless a more grandiose vision of abstract methods/interfaces is in the plans
- what would it hurt?

kind regards.

-a
-- 
share your knowledge.  it's a way to achieve immortality.
- h.h. the 14th dali lama