The Totally Unofficial Ruby coding style guide | Hacker News Reader

The Totally Unofficial Ruby coding style guide

github.com

14 pointsbozhidar26 comments

> Prefer map over collect, find over detect, find_all over select, size over length. This is not a hard requirement, though - if the use of the alias enhances readability - it's ok to use it.

Not too sure about that... I prefer collect/detect/select/reject...

> Keep existing comments up-to-date - no comment is better than an outdated comment.

Ambiguous sentence warning!

Using #find in a Rails project tends to be a mistake, especially when used on an ActiveRecord association proxy.

Although it's the naming pattern I've always used for constants (both in Java and Ruby code), I've never heard of it referred to as "SCREAMING_SNAKE_CASE". I like that.

I like the idea of an unofficial style guide on github - companies can fork & edit, then new hires can diff against the version they're most familiar with.

This breaks once the first editor with proportional width font support becomes popular in Ruby land:

  kind = case year
         when 1850..1889 then "Blues"
         ...

I also have a question that I have always wanted to ask. I am not a native speaker of English. Are "if not" and "unless" really the same thing?

Does this:

  def foo(x, y, z)
    destroy_universe unless all_arguments_valid?
    # more code...

and this:

  def foo(x, y, z)
    destroy_universe if not all_arguments_valid?
    # more code...

really have the same implications? "unless" makes it sound a tiny bit as if "all_arguments_valid?" was the exception - to me at least. Does anyone else use "if not" based on this gut feeling sometimes?

As a native English speaker, I would say that "unless" usually implies that the condition is exceptional, which is why I try to avoid code like "handle_error unless there_is_no_error".

I'm clueless about ruby. Never learned it. But this makes me cringe (obviously I'm coming from a different context, but is this really a good idea? And who wants to have a table like this?) ..

>The length of an identifier determines its scope. Use one-letter variables for short block/method parameters, according to this scheme:

  a,b,c: any object
  d: directory names
  e: elements of an Enumerable
  ex: rescued exceptions
  f: files and file names
  i,j: indexes
  k: the key part of a hash entry
  m: methods
  o: any object
  r: return values of short methods
  s: strings
  v: any value
  v: the value part of a hash entry
  x,y,z: numbers

I'm a heavy Ruby user and I've never seen or heard of this until now. The rest of the document is pretty close to what I follow, but this one is theirs and theirs alone.

This Ruby style guide is based on https://github.com/chneukirchen/styleguide/blob/master/RUBY-... , as stated in the introductory paragraph. That style guide also contains these conventions for one-letter variable names.

Many others have forked this guide and made modifications according to their tastes.

In the past, I've used naming methods like this, and at first, it seemed really intuitive. But it becomes unnecessarily dense over time, and often results in awkward readability.

I've moved instead to simply using reasonably descriptive variable names where the type is easily inferred. The extra type information isn't missed.

  sZipCode = "90210"

really isn't necessary. Instead:

  zipCode = "90210"

works just fine. And leaving out the type information for a variable with no repercussions is 95% of use cases for variables.

No, you're talking about Hungarian notation, the guide is talking about standardised one-letter names for certain variables.

The way I'm reading it, they're casting a wider net than Hungarian notation, but it's similar to it.

It seems pretty clear to me: "Use one-letter variables"

On re-reading, you're right. My fault for giving them the benefit of the doubt. One letter variables? I'm a little bit speechless.

I don't recommend one letter variables. I don't know if I've ever seen an official style guide that has.

> I don't recommend one letter variables. I don't know if I've ever seen an official style guide that has.

Not that familiar with idiomatic Ruby, but using one letter variables as iterators in for loops (and some other things) is pretty idiomatic C:

    int i;
    for (i = 0; i < queue_size; i++)
        queue[i] = get_rarest_peer(t->peer_list);

The key modifying phrase was "for short block/method parameters." The authors aren't advocating one letter variables throughout your code, only in situations like:

  [1, 2, 3].each { |e| puts e }
  Object.methods.each { |m| "Method is: #{m}" }

Even as such, using full words is barely any more typing, and more readable.

  [1, 2, 3].each { |value| puts value }
  Object.methods.each { |method| "Method is: #{method}" }

I consider that a better habit to have than using single-character variables. And style guides should be about encouraging the best habits possible.

Interestingly enough, some of the entries in this list are the conventions I tend to use for "short block level params."

If you're not used to Ruby, here's an example of what he's referring to:

To work with the keys and values of a hash (dictionary / associative array) I use the .each method on the hash itself. The .each method gives me access to the key and value of each entry in the hash.

    hash = {"name => "Homer", "age" => 42}
    hash.each{|k, v| puts k + " " + v}

Where 'k' is key, and 'v' is value.

I never really gave much thought to "standardizing" this.

As far as I am concerned, the full name is more readable. A few keystrokes mean nothing in the grand scheme of things. Readable code does.

   hash.each { |key,value| puts "#{key} #{value}" }

It's all about style. Which is what makes it really interesting. In your implementation you used string interpolation, a different kind of shortcut. And in my example, I used + to make it more readable for the parent poster who said they weren't familiar with Ruby.

Interesting how "more readable" is somewhat objective, isn't it?

I chose interpolation in this example because I found the lack of any break character between the method and the variable to not read well.

    puts k + " " + v

Does that execute as puts(k) + " " + v, puts(k + " ") + v or any other combination? While those of us familiar with Ruby know the answer, I would still argue that it takes greater cognitive resources to evaluate over the single string, especially in the presence of a syntax highlighting editor who clearly defines the string boundaries in colour.

You are right that it is definitely subjective. Coding is user interface design, but we don't usually have the luxury of processes like A/B testing to validate our work like other interface designers do. It would be interesting to put both of our code samples along with some other variations in front of an audience and see how they are received.

I've done some of that in my teaching - people get the string addition right away since that's how people write in JS and other languages they already know. I immediately show how string interpolation works (by showing how it automatically calls .to_s to handle type issues.)

When I've tried to jump right into string interpolation, people don't quite get what's going on, which resulted in me having to backtrack and do addition anyway.

But that's just my experience.

I do not understand why the subclauses of `case` are not to be indented.

For the same reason you don't indent 'else' relative to 'if'. It avoids double-indentation and isn't really necessary. All of the lines under 'case' will begin with one of 'when', 'else', or 'end' and are thus easy to spot without indentation.

I am yet to hear anyone give a compelling argument in favour of parenthesising arguments to a method:

  def method_name(arg1, arg2)

instead of

  def method_name arg1, arg2

especially when they do not like empty parentheses for no args

  def method_name()

and they just love to omit the parentheses when actually using a method

  puts "odd"

Why the inconsistency? Unnecessary parentheses are unnecessary! When in doubt .. let the args out!

edit:

> Avoid hashes-as-optional-parameters. Does the method do too much?

And I'm totally against this. This is an extremely useful pattern and can be key to increasing readability. I basically insist on opts hashes on any method with more than 2 args. Wow, you can see what is intended rather than Model.do_something(3, false, false).

Any big application has methods that take a lot of switches. The opts hash pattern lets you at least label them, rather than rely on obscure argument order. And it lets you set defaults on the args in a sane way (rails' famous reverse_merge!). Why would anyone be against that?

On the hashes part, it's tricky when reading the method itself what the options are. For example, many of the Rails helper methods that take html_options ={} are only documented in one place.

So it's cleaner from the side of invoking the method, but relies on the developer of the method to heavily document what the hash's options are. That's the only thing I've noticed.

Reply on news.ycombinator.com