RuboCop as compiler
Ruby is not a compiled language.
You can write code which has obvious flaws and Ruby will run it and then it will
fail at runtime. For example:
puts "hello world"
puts hello world
That produces this output:
$ ruby lol.rb
hello world
/Users/max/Desktop/lol.rb:2:in `<main>': undefined local variable or method `world' for main:Object (NameError)
Some other languages wouldn’t even run that program. For example, the same code
in Go:
package main
import "fmt"
func main() {
fmt.Println("hello world")
fmt.Println(hello_world)
}
Running that produces this output:
$ go run lol.go
# command-line-arguments
./lol.go:7: undefined: hello_world
But Ruby can’t run anything. Look at this bullshit:
puts "hello world"
def lol
puts "lol world"
lol
Running that produces this output:
$ ruby lol.rb
/Users/max/Desktop/lol.rb:7: syntax error, unexpected end-of-input, expecting keyword_end
Notice: it doesn’t even output “hello world”; it just straight-up fails to run.
You might say it doesn’t compile.
Ruby actually has a command line flag for checking the syntactic-correctness of
a program:
$ ruby -c lol.rb
/Users/max/Desktop/lol.rb:7: syntax error, unexpected end-of-input, expecting keyword_end
$ ruby -c ok_program.rb
Syntax OK
This is useful, but only to a point. It means your programs will usually run,
but you’ll have more errors at runtime than you would writing in a language like
Go (for example).
I barely know Go, but in the small exposure I’ve had, I’ve really enjoyed how
nit-picky the compiler is. For example, this program:
package main
import "fmt"
func main() {
msg := "Hello world"
other_msg := "lol world"
fmt.Println(msg)
}
Running it produces this output:
# command-line-arguments
./lol.go:7: other_msg declared and not used
What! I can’t run my program because I declared a variable but then didn’t use
it?? Who cares?? Go cares! And I kind of do too, now. Why have it if you don’t
need it? Go kind of forces you to write really intention-revealing code and to
clean up anything which might obscure your intentions. That’s great.
Ruby doesn’t care as much about that.
msg = 'hello world'
other_msg = 'lol world'
puts msg
That’s fine:
$ ruby -c lol.rb
Syntax OK
$ ruby lol.rb
hello world
So now your code has this random unused variable. It’s not really hurting
anyone or anything. In theory it has a performance impact, as it’s allocating
an object you don’t really need it to, and if this code is run a ton that could
matter. But more importantly, I think, it’s just clutter. When people come
across this code in the future they won’t know why it’s there, but they might
assume it’s there for a reason, and they’ll mentally mark this area of the code
base as kind of strange and unknowable.
RuboCop is a gem which can help bring Ruby
closer toward Go levels of nit-pickiness, and I’m a huge fan of it. I recommend
including it in your Ruby projects and running it alongside your tests to
enforce adherence to its rules (“cops” in its parlance).
Running that same ruby program through RuboCop produces this output (note: you
have to gem install rubocop first):
$ rubocop lol.rb
Inspecting 1 file
W
Offenses:
lol.rb:2:1: W: Useless assignment to variable - other.
other = 'lol world'
^^^^^
1 file inspected, 1 offense detected
Awesome! Now we know our code contains some offense and might be confusing our
collaborators, and we know exactly where to make the change.
RuboCop as code style nit picker
RuboCop is also very opinionated about code style. For example, it will complain
if you aren’t consistent about using single or double quotes, or if you aren’t
consistent about using two spaces for indentation, or if you leave spaces at the
end of your lines.
I recommend configuring it to your taste and to not feel guilty about disabling
cops which you don’t find valuable. As a tool, it adheres to the “strong
opinions, weakly held” mantra: it’s very easy to bribe this cop into changing
its opinions by adding a simple yml file to the root of your project.
The Go compiler isn’t picky about things like code style, but Go ships with a
secondary, optional tool called gofmt which is extraordinarily opinionated:
it straight-up rewrites your code to follow Go style conventions.
Similarly, many RuboCop cops are auto-correctable. Consider this program a
“before picture”:
class Dog
def initialize(name:name)
@name=name
end
end
milo = Dog.new(name: "Milo")
p milo
Kind of ugly looking, but it’s syntactically valid:
$ ruby -v
ruby 2.0.0p451 (2014-02-24 revision 45167) [x86_64-darwin14.3.0]
$ ruby -c lol.rb
Syntax OK
$ ruby lol.rb
#<Dog:0x007fbe64207a40 @name="Milo">
So let’s try autocorrecting it:
$ rubocop lol.rb --auto-correct
Inspecting 1 file
W
Offenses:
lol.rb:1:1: C: Missing top-level class documentation comment.
class Dog
^^^^^
lol.rb:2:1: C: [Corrected] Extra empty line detected at class body beginning.
lol.rb:2:23: W: Circular argument reference - name.
def initialize(name:name)
^^^^
lol.rb:3:1: C: [Corrected] Extra empty line detected at method body beginning.
lol.rb:3:1: C: [Corrected] Trailing whitespace detected.
lol.rb:4:1: C: [Corrected] Trailing whitespace detected.
lol.rb:4:5: W: end at 4, 4 is not aligned with def at 2, 2.
end
^^^
lol.rb:4:10: C: [Corrected] Surrounding space missing for operator =.
@name=name
^
lol.rb:5:10: C: [Corrected] Surrounding space missing for operator =.
@name=name
^
lol.rb:8:22: C: [Corrected] Prefer single-quoted strings when you don't need string interpolation or special symbols.
milo = Dog.new(name: "Milo")
^^^^^^
lol.rb:9:22: C: [Corrected] Prefer single-quoted strings when you don't need string interpolation or special symbols.
milo = Dog.new(name: "Milo")
^^^^^^
lol.rb:10:1: C: [Corrected] 2 trailing blank lines detected.
lol.rb:11:1: C: [Corrected] 2 trailing blank lines detected.
1 file inspected, 13 offenses detected, 10 offenses corrected
Afterwards, the program looks like:
class Dog
def initialize(name:name)
@name = name
end
end
milo = Dog.new(name: 'Milo')
p milo
It’s not perfect. I’m surprised it didn’t autocorrect the indentation on the
first end. But it’s neat that it did as much as it did.
EDIT: I opened an issue about this surprise and it turns out they don’t
want to autocorrect that unless you really opt in.
In the past, I’ve written about how Ruby Keyword Arguments aren’t Obvious,
and mentioned “circular argument references” as a mistake I had to learn not to
make. In an attempt to give back to others like me, I submitted a pull
request which adds a cop to RuboCop that checks for the presence of those
circular argument references and warns you about them. This is particularly
useful on Ruby 2.0.0 and Ruby 2.1, which don’t emit warnings about their
presence as Ruby 2.2 does.
contributing to RuboCop
Contributing to RuboCop is somewhat intimidating because, as you might imagine,
its code base has very high standards. It also seems like it ought to be very
complicated, because the project needs to be able to statically analyze code
in order to complain about it.
Fortunately, the maintainers are very clear and quick in their feedback, and
happy to merge things which seem useful. And the code base has many examples of
how to write a cop. A cop is a class which inherits from RuboCop::Cop::Cop.
require 'rubocop'
require 'active_support/all'
RuboCop::Cop::Cop.subclasses.count #=> 226
# (required active support for the subclasses method, which I love)
Once you subclass Cop, your class will be on duty and RuboCop will ask it if
it’s offended by the code it’s analyzing. You just need to tell it which types
of code you care about. RuboCop thinks of Ruby code as a tree of nested nodes,
each having a type. For example, when you assign a local variable, RuboCop sees
that as a node whose type is :lvasgn. Let’s say you wanted to write a cop
where local variables aren’t allowed to be named “harold”. You would write that
like this:
# encoding: utf-8
module RuboCop
module Cop
module Lint
class Harold < Cop
def on_lvasgn(node)
local_variable_name, value = *node
return unless local_variable_name == :harold
add_offense(node, :expression, 'Do not name local variables harold')
end
end
end
end
end
The trickiest bit is learning how RuboCop “sees” code as nodes and learning what
the different parts are called. That comes from looking through the existing
examples and experimenting. It’s fun, I recommend it. I added one other cop
on a bored evening, about discouraging option hashes.
RuboCop as teacher
This summer, I coordinated a group of 5 developer interns at work. I helped pick
them out, so I knew they were all very bright but not super experienced with
Ruby. We asked them to study a bit and follow the Rails Tutorial Book
before starting to help get them on the same page, but we didn’t expect them to
know Ruby conventions or best practices.
From the beginning, their project had RuboCop linting their code, with zero
configuration. I warned them, “you’re going to hate this”. On their last week,
I asked them if it was helpful, and they all said yes, but that it was often
very annoying. Some of them liked it more than others. One even made a
contribution to RuboCop fixing an issue in the cop I added. They produced a
very interesting code base. Superficially, it’s immaculate. They picked up a few
tricks from RuboCop suggestions. More than one cited guard clauses as a
thing they wouldn’t know about otherwise.
The class length maximum (100 lines) and the method length maximum (10 lines)
were both unhelpful. They’re meant to guide you toward following the single
responsibility principle, but if it’s not something you’ve internalized, it just
sort of makes you stuck and frustrated.
I came to think of RuboCop (and, later, coffeelint and scss-lint) as
an automated layer of mentorship filtering out some potential questions that
didn’t need to reach the human layer, so that layer could be reserved for more
interesting problems and discussions.
RuboCop as totalitarian police state?
I do think of programming as a creative outlet, but don’t worry about linters
inhibiting your creativity; think of it like a poetic form with strict rules,
like the sonnet. There’s something very satisfying about consistency, right?
