Enumerable Anti-Patterns

Enumerable methods are one of my favorite parts of Ruby. Enumerable anti-patterns, however, can make things not-so-fun. Let’s explore some ways these helpful tools are abused, and how to fix them.

Enumerable anti-patterns #1: Don’t use a shovel as a hammer

Instead:

Explanation:

Whenever you initialize a variable to a new array, then shovel into that array from an each block, be suspicious. There are cases where this might actually be necessary, but usually what you’re doing is re-implementing a method that already exists: #map.

Enumerable anti-patterns #2: Don’t use #map when you mean #each

#each acts on every item in a collection without caring about the return value. It returns the collection you’re iterating over. #map acts on every item in a collection and does care about the return value. It returns a new collection containing the return value of all the operations it performed.

If you iterate over a collection, calling a method on each item where the side effects are the primary purpose of the operation — that is,  where you don’t care about the return values — using map can be confusing. In the example above, because we’re mapping over a collection on the last line of the method, the return value of the map operation will be the return value of our method. This could potentially delude a reader of our code into thinking we care about this information when, in fact, we do not.

Instead:

By using #each, we’re telling our reader that we don’t care about the return values of our enqueue operations.

Counter example:

Here we want to know whether every notification was delivered successfully, and to return to the caller whether or not this was the case. Using an explicit return, while not strictly necessary, indicates in no uncertain terms what our intentions are: we are returning a value.

Enumerable anti-patterns #3: Selecting instead of detecting

Instead:

#select goes through the entire collection, finding all matching entries. If there should only be zero or one matches, or if you only care about the first match you find, use #detect instead. Similarly, if you only want to know whether there are any matches, use #any?:

Counter example:

If you really do want all the matches, by all means use #select

You might be noticing a pattern here: if you find yourself chaining enumerable methods together, there might be room for improvement.

Speaking of select:

Enumerable anti-patterns #4: Over-using enumerable methods with ActiveRecord

The projects we work on as developers influence our comfort level with various parts of Ruby and/or Rails. If you’re more comfortable working with collections and Enumerable, you might not immediately notice what’s wrong with the above. We’re searching a collection of posts for the first one that matches params[:id].

If you’re used to using ActiveRecord, you would probably write this as

For a small hobby app with a few dozen posts, the difference in performance is likely negligible. But for a production app with millions of records, the latter is the clear winner. SQL – particularly with a primary key – is purpose-built for this kind of task. Finding a single record using an index with extremely high cardinality is about the cheapest operation in SQL.

Pulling all records from the database, loading them into memory, then running each through a block until one returns true, on the other hand is rather inefficient.

Enumerable methods are better for smaller collections, cases where SQL operations aren’t available, or where you aren’t operating directly on database tables or ActiveRecord models.

Final Thoughts

These are just a few examples of using enumerable methods in ways they’re not meant to be used. The reason these misuses are bad is not because they’re “wrong” or even because they’re inefficient. Code is meant for people as much as (if not more than) it is for computers. We’re communicating our intentions to the next person to come along. Taking the time to communicate clearly what we intend makes it easier to review pull requests. It also makes it easier to make modifications down the road. Be kind to others.

Posted in Uncategorized | Tagged , , , | Leave a comment

Test names and readability

What’s in a Name?

It’s important to choose a useful name for a test. If tests are documentation, test names are the chapter headings.

Test Names Should Not Include Should

There’s nothing wrong with the word “should.” It’s just not necessary. It’s one more word to read when trying to understand a test. “It should divide by four” and “It divides by four” express the same idea in a test name.

There are several issues with the above. First of all, it contains should. Second, it runs roughshod over ‘it.’ If I read the line out loud, “it foo…” does not make sense. Also, that’s a lot of words. As a developer, I want to be able to skim the tests so that I can find the test case I’m looking for.

Isn’t that better? In addition to being more readable, it makes it painfully obvious that we’re missing another test case. Let’s add it.

Be Specific

Now we have another issue: two test cases called “returns the correct value.” Come to think of it, that’s also pretty generic. Probably most test cases could be called “it returns the correct value,” “it has the intended side-effects,” or “it has the intended side effects and returns the correct value.” The question is, how would you describe the value and/or side-effect we’re looking for? Not the actual value, but its significance or meaning.

Cool. Now in this one-assertion test it doesn’t matter as much, but say we returned the bars themselves instead of the count and needed to make several assertions. Like test names, variable names in assertions improve readability.

A Bit of Context

These tests are written for Minitest. If you’re using RSpec, you have an additional tool at your disposal: The context block.

Use describe when specifying the subject of the test – the class or method. Use context when talking about the circumstances under which we’re testing.

Takeaways

Let’s write some tests for our tests:

  • it “begins with a verb, not a subject” (‘it’ is the subject)
  • it “reads like a sentence” (‘it’ is the first word of the sentence)
  • it “does not contain when or if” (those belong in describe blocks)
  • it “is short” (and skimmable)
  • it “doesn’t use should as the verb”
  • it “is specific about the expected result” (what is the significance of the correct or expected result?)
Posted in Uncategorized | Tagged , , , | Leave a comment

Benefits of Keyword Arguments

When I first heard about keyword arguments in Ruby, I’ll admit I regarded them as a bit of a toy. Part of this was because they were only supported by Ruby 2.0 (2.1 if you wanted required kwargs), and at the time most of my projects were using 1.9. But I also didn’t see, at first, how they fundamentally differed from using a params hash.

What are Keyword Arguments?

What does this do for us? The second and third options allow us to make a little trade. Instead of having to remember the order of the arguments, we just have to remember their names.

When Should I Use Keyword Arguments?

Is this a good trade?

It depends. From one perspective, connascence of name leads to looser coupling than connascence of position. Looking at it this way, keyword arguments are always a good trade.

On the other hand, look how much shorter and more readable option one is, both to define, and to call. There are particular circumstances that strongly indicate the use of keyword arguments:

First, if your method signature is likely to change. Adding new param, especially in the middle of the list, can break every piece of code that calls your method, or worse, introduce subtle bugs while appearing to continue to work.

Second, if you have a long list of params. It’s a lot easier to get two or three arguments right in a method call than six or seven.

Another Use For Keyword Arguments

Keyword arguments can also be mixed and matched with other types of parameters. This could be used to write Smalltalk/ObjectiveC type methods, possibly in a DSL as an alternative to the traditional currying style:

Traditional:  expect(thing).to_receive(:foo).with(1, 2)

Smalltalk-esque:  expect(thing, to_receive: :foo, with: [1, 2])

Posted in Uncategorized | Leave a comment

Wire Up Your Dependencies With Wiredep

One of my favorite tools for building Angular apps is Wiredep. Manually including javascript and CSS dependencies into an HTML file can be a pain.

It’s not that big of a deal, really, but figuring out which files a bower package provides, remembering their paths, and typing them into the right spot in the right file can break you out of your flow state in a hurry.

Assuming you’re already using bower to manage your dependencies, it will probably take less time to get wiredep up and running than it would to set up another dependency without it.

First, install wiredep:

Next, edit your top-level html file to tell wiredep to put the dependencies:

Now run the following:

Wiredep will insert all the CSS and javascript include tags for the files provided by your installed packages:

Rerun the command each time you install a package with bower instead of manually adding the includes.

Be sure to keep any non-bower includes outside the bower/endbower sections or they will be clobbered next time you run wiredep.

For bonus points, add a Grunt task so you can just type grunt wiredep . With grunt-wiredep, there’s even a way to update your karma.conf.js too.

Posted in Uncategorized | 1 Comment

self in Ruby

Using self in Ruby comes naturally if you’ve been writing Ruby for any length of time. It’s easy to gloss over its meaning and significance, however.

Take, for instance, the following class.

Why didn’t #blend_in work as expected? We missed a self. We should have written self.make = new_make.

It’s easy and sometimes tempting to memorize heuristics like “always use self. when calling a setter.” While rote memorization can help keep beginners from getting mired in the details, at some point it’s important to dig into the why.

Obviously if we leave off self., we’re assigning a local variable. But why does Ruby do this?

Ruby specifically tries to make setters look like regular variable assignments. In most cases, this makes Ruby very simple and elegant. It can also introduce ambiguity. Does make = new_make mean #make=(new_make) or does it mean ‘assign the value of new_make to a new local instance variable called make?’

There’s no way for Ruby to know. Did you notice I clarified the second case by writing it out in English? That’s because there’s no clearer, more unambiguous way to write it in Ruby. Because there’s no other way to write it, if Ruby defaulted to using a setter when one existed, there would be no way to define a local variable with the same name as a setter.

While it’s generally not good practice to do so, there are cases where it might be useful.

Using self in Ruby getters

So why don’t you need to use self. when calling a getter? In some cases, you do!

 

Posted in Uncategorized | Leave a comment

List of Online Code Checkers

We’ve all been there. There’s that one task you’ve been avoiding on your todo list. It’s not even that hard, to be honest. It just involves something finicky, fiddly, and unfamiliar. Maybe it’s a particularly tricky regex or a shell script that needs written. Luckily, it’s the 21st century and there are a plethora of resources to aid coders in these tasks. May I present The Big List of Online Code Checkers:

Devops Stuff

Crontab: http://crontab.guru
mod_rewrite Rules: http://martinmelin.se/rewrite-rule-tester
Shell Scripts: http://www.shellcheck.net
SPF Record: http://www.spfwizard.net
Subnet Calculator: http://www.subnet-calculator.com

Runners up – local devops tools for checking syntax

Apache: apachectl configtest
Bind: named-checkconf /etc/named.conf
Nginx: nginx -t -c conf/nginx.conf
Postfix: postfix check
SSH: sshd -t – Use this every time if you don’t want to get locked out :)

Coding Playgrounds

These are great for spiking on a solution in a less-familiar language.

Collaborative Editor: http://collabedit.com
Elixir: http://elixirplayground.com
Go: https://play.golang.org
Javascript/CSS/HTML: https://jsfiddle.net
PHP: http://www.tehplayground.com
Python: http://mathcs.holycross.edu/~kwalsh/python
Regular Expressions: http://rubular.com
Ruby: http://rubyfiddle.com
Sass: http://www.sassmeister.com
SQL: http://sqlfiddle.com

Online Code Checkers, Formatters & Converters

CSS validator: https://jigsaw.w3.org/css-validator/
HAML to ERB converter: https://haml2erb.org
HTML Tidy: https://infohound.net/tidy/
HTML validator: https://validator.w3.org
Javascript Minifier: http://jscompress.com
JSON validator/formatter: https://jsonformatter.curiousconcept.com
RSS/Atom validator: https://validator.w3.org/feed/
YAML: http://www.yamllint.com

SEO

robots.txt: Google Webmaster Tools
Structured Data: https://developers.google.com/structured-data/testing-tool/
XML Sitemap Generator: https://www.xml-sitemaps.com

This is just a small sampling of what’s available. There are online code checkers, validators, converters, formatters, and generators for just about anything you can imagine. Next time you find yourself with a dreaded task in

What online code checkers, formatters, or generators do you use on a regular basis?

Posted in Uncategorized | Leave a comment

Handling Exceptions in Ruby

Handling Exceptions in Ruby is Easy!

Exceptions are Ruby’s way of allowing us to attempt to recover from errors. The basic syntax for handling exceptions in Ruby goes something like this:

We can gather more information from an exception like so:

Notice we rescued StandardError and not Exception. There are many types of exception you might not necessarily want to rescue. For example, pressing CTRL+C or sending SIGTERM to the process would not work as expected and you might have to resort to SIGKILL.

Implicit Contexts

It’s not always necessary to explicitly type begin. Class, module, and method definitions and ruby blocks serve as implicit rescue contexts.

Rescuing exceptions is a good use case for a logger.

Multiple Exception Handling

You can handle multiple types of exception differently. Just be sure to put specific exception types before StandardError if rescue it.

Re-raising Exceptions

You can re-raise an exception after doing something with it. raise knows to re-raise the exception in the rescue context.

Retrying

You can retry the error-prone task after rescuing.

Just be sure to check whether you’ve already retried first to avoid an endless loop if the fix doesn’t work.

Cleaning Up

In some situations there’s code that needs to run whether there’s an exception or not. The most common example is closing a file handle

Defining Your Own Exceptions

Failing

Use fail rather than raise to surface an exception unless you are reraising as above.

Posted in Uncategorized | Leave a comment

Using dotenv to store environment-specific config

What Is dotenv

dotenv sets environment variables from a .env file,  to be accessed via ENV in Ruby. Using dotenv allows you to specify important global, environment-specifc configuration settings like API keys and secrets, usernames and passwords, and URIs in a file that’s not checked in to version control. These settings can then be accessed at run time using ENV['VARNAME'] .

Oh you mean like config/database.yml or config/environments/**.rb in Rails?

A lot like that. However, those files are generally checked in to version control software. It’s not a good idea to have important production passwords in your repo.

Why Should I Use dotenv

Fundamentally, configuration is not part of your application. It doesn’t belong in the same repo as the app itself. Putting it there can create numerous problems:

  • Developers accidentally or naïvely committing changes that work for them but not others to a shared development-specific config file, breaking other developers’ dev environments
  • Configuration containing sensitive passwords getting accidentally checked into version control, potentially leading to a security breach
  • Creation of additional environments for QA, staging, etc. that are ‘just like production, except…’ leading to bloat and churn in config files

Using dotenv

  1. Add .env to your .gitignore
  2. Add dotenv to your Gemfile:
    gem 'dotenv-rails' if you’re using Rails or  gem 'dotenv' otherwise
  3. Create the file .env in the root directory of your project and specify variables inside, one per line, like so:
    MY_CONFIG_VAR=ABC123
  4. If you’re using Rails, you should be able to access ENV['MY_CONFIG_VAR'] , but certain cases may require more tweaking, so see the readme if you have trouble
  5. If you’re using another framework or building a plain old Ruby app, add this somewhere that will be loaded before you need to access any variables:

     
  6. Set the same variables in a .env file for each environment (staging, production, etc.) and place these directly on each server (or with the code for configuring/provisioning servers)
  7. You’re done!

Strictly speaking, using dotenv in production is not recommended, so long term it may be worthwhile to find another way of setting the necessary environment variables. That said, many do use it in production without issue.

By way of example for step six, if you use Capistrano to deploy your app, the production .env file would live in the shared directory and be symlinked during deploy.

Posted in Uncategorized | 1 Comment

Building a Rack App / Ruby Web App

Have you ever wanted to build a super basic ruby web app? Maybe a single-page sort of thing, something that displays the temperature in your backyard or the number of emails in your inbox. The sort of thing where a simple HTML page won’t work, but a framework is overkill.

PHP got its start doing this sort of thing. While you can build object-oriented MVC frameworks with PHP, the reason so many people started using it was because if your server was set up for it, you could just rename index.html to index.php and paste in some code between <?php and ?>. Done.

Alas, it’s never been quite that simple with Ruby, but we do have Rack.

About Rack

What’s Rack? It’s how frameworks like Sinatra, Rails, Hanami, etc. talk to web server software. Or as the Rack website puts it “Rack provides a minimal interface between webservers that support Ruby and Ruby frameworks.”

Also from the Rack website, here’s a super simple Rack app:

This would go in the file config.ru. This file tells the rackup command what to do to run your application. (Ever notice that Rails apps have a config.ru?)

The command ‘run’ tells it what to run. The thing it runs is a Proc that gets passed something called env, then returns an array with ‘200’ (as in the HTTP status code OK), a hash of response headers, and an array of strings.

While it does a great job of showing just how simple the interface is, the code above isn’t very exciting or useful. Let’s make something that does stuff! Inspired by isitchristmas.com, I bring you: Is it April Fools?

Building a Rack App

To start with, let’s write an index.html.erb:

Now let’s build something more classy/object-y than a proc. Here’s my_rack_app.rb:

In case you’re wondering, ERB#result accepts an optional instance of Binding, which lets us pass in our current execution context. That’s how we’re able to use the self.april_fools? method within the erb file. If we didn’t need this, we could just call #result with no arguments, and it would be given a new context.

Because we defined self.call, the MyRackApp class will behave like a proc. This will allow us to make config.ru much prettier:

So easy!

Running Our Rack App

To see it in action, use the rackup command in the same directory as your config.ru. rackup runs on port 9292 by default, so go to http://localhost:9292 in your browser to see it.

Posted in Uncategorized | Tagged , | Leave a comment

The Ruby Logger – Keep a log

You’ve used the Ruby Logger if you’ve ever built a Rails app, or even started up a development server and watched the output scroll by. But because Rails provides logging out of the box, it’s not often necessary to think about it.

If you’re building a plain old ruby app, however, logging is something you might think about implementing at some point. When that time comes, Ruby’s built-in Logger class has your back.

Instantiating a Ruby Logger

That’s all there is to it.

Of course instead of writing to stdout, you could also write to stderr, a file (and optionally set up rotation of log files) or even a custom class that implements write and close.

The custom class option is useful if you want to log to both stdout and a file, want to create a dummy log for testing, or if you are using something like highline to do your IO.

Configuring your Log

Severity threshold

Logger has the following severity levels from least to most severe:

Logger::DEBUG, Logger::INFO, Logger::WARN, Logger::ERROR, Logger::FATAL, Logger::UNKNOWN

These are the constants you can set the severity threshold to. (They correspond to 0, 1, 2, 3, 4, and 5 respectively, but use the constants whenever possible.) Anything below the severity threshold will be ignored.

Set the threshold like so:

Better yet, set environment-specific values in the environment’s dotenv file.

App name

Formatter

The default is an instance of the Formatter class. If you want to specify your own, you can subclass Formatter, or use a proc. The following example would print only the message, ignoring everything else.

Sending messages to the Ruby Logger

The Ruby Logger has a method for each of the error levels

For more information, check out the documentation.

Posted in Uncategorized | Tagged , | Leave a comment