From: Justin Bailey <jgbailey@...>
Date: 2007-01-10T02:24:12+09:00
Subject: Re: [ANN] Elements of Ruby Style

On 1/9/07, Jeremy McAnally <jeremymcanally@gmail.com> wrote:
> Anyhow, look at the list, and let's talk about what should be on there.
>
> Visit http://www.elementsofrubystyle.com/ .

I like what you've got and for most cases I agree with your style
guidelines. I've been programming Ruby for about 1.5 years and have
created several gems for distribution, so I've seen many of the issues
you cover.

My comments:

* A section on commenting code, especially so it is RDoc compatible
(i.e. place all text in contiguous lines starting with #, or use
=begin, =end for particularly long comments).

* When commenting, indicate the type of object returned and the type
of those accepted. Not in the strong-typing sense, but for
documentation purposes. Trying to figure out what methods are
available on objects returned can be a real trial-and-error process if
it's not well documented.

* (Personal style) - Place all "assertion" handling code at the
beginning of each method. For example:

  def some_method(arg1, arg)
    raise "Arg1 cannot be nil" if arg1.nil?
    raise "Arg1 must be a number" unless arg1.is_a?(Numeric)
    ...

 I've found its a nice way to document what a method considers legal.

* (Personal Style) - Don't use a string to define a new method unless
you need interpolation. You usually only need it when code within the
method must be different based on some conditional.

* Finally, I think you should make explicit mention of the DRY principle.

A few specific points I don't agree with or have questions about:

* 2.h.i - " There is no advantage  ... " - Single quoted strings do
not interpolate, while double-quoted do. You seem to be stating there
is no difference between them.

* 2.h.iii - "Multi-line strings should be expressed ..." - You mention
that here-docs should not be used if  interpolation is needed. I'm not
sure why, because interpolation works fine in here docs.

* 2.c.ii - "Curly braces should be used if the return value is
desired" - Why? This isn't a style I've seen much in the wild. Is it
used throughout the Rails source?

* 2.c.iii - "Use parametrized variables rather than accessing scope
variables" - This seems to say you shouldn't take advantage of the
closure property of blocks (i.e. that in-scope references are carried
around and can be used). If that's true, why? If not, a clarification
should be made.

Hope this helps. Looks like you are off to a great start. Is an RSS
feed going to be available soon?

Justin