Ruby Best Practices

Conventions to Know About

When we walked through Haml in the previous example, we could see that it had a high degree of discoverability baked in through the conventions it uses. Though Ruby is free-form in nature and allows you to structure your files in pretty much any way you want, it makes sense to standardize in most cases. Making your project easily accessible to your users so they can figure out some questions on their own is one of the easiest things you can do to make your project more maintainable. Though each of the tips in this section may seem a bit trivial, combining them can be very powerful.

What Goes in a README

A somewhat universal software development standard is to have a README file that provides a starting point to your software. Finding the right balance of information to include in this file can be a bit of a challenge.

Minimally speaking, a good README should include everything that is necessary to begin working with a project, and nothing more. For starters, you’ll need a brief one- or two-paragraph description of what the project is for, and what problems it is meant to solve. Drawing from another good open source example, we can see that the README for James Gray’s HighLine library opens in exactly this way:

== Description Welcome to HighLine. HighLine was designed to ease the tedious tasks of doing console input and output with low-level methods like gets() and puts(). HighLine provides a robust system for requesting data from a user, without needing to ...