Weekend Ruby: Coding Quality with Style

Photo by pdxnielson

It seems the community has started to work towards a common set of guidelines for a beautiful and readable Ruby code. Nice…

The idea behind any style guide is largely based on aesthetics and readability. The number of spaces to use for indentation, how to break statements into several lines, when the chain of statements is to be broken into several clauses — all is simple, yet no less important than the code itself.

These days we have many self-taught programmers who neither have a taste nor any special education. What’s worse, many of them don’t really care about clarity and maintainability of their code, preferring to quickly throw some pieces together to get their payments quickly without any proper design, testing, formatting and anything else. It’s a “poor job” and a “job poorly done”. I encourage everyone who purchase code to demand The Quality, and I equally encourage everyone who produces code to do their homework — study the best code samples, read guidelines, do their testing and follow (if not all, but as many as possible of) the best established practices. It’s the hard work that eventually becomes fun.

Here’s one of the attempts to summarize good coding practices into a guideline that I stumbled upon this week: The Elements of Ruby Style. It’s obviously incomplete, but it’s a good start that has all chances to evolve. There always will be people who disagree with certain points (including me, who would rather use “boolean ? 3 : 5″ instead of “if boolean then 3 else 5 end”, which is redundantly complex), but if you need to start from somewhere, it still is a great starting point.

In the same vein, here’s Rails Code Quality Checklist and the Code Quality Checker. These are mostly for the code design control, but since we talk about code quality today…

Enjoy your weekend studies!

Productivity Tip

Today, as I was playing with ideas after a big chunk of work, one interesting thought came, and it’s worth sharing. Everybody likes when the job is simple, straightforward and easy to do. Sometimes though times come when an assignment is … well, different.

I like to shoot these tasks first and, speaking in the context of PROgramming, like to make everything possible to never get back. If it implies writing a hundred of tests, that’s fine, just never again… you hear me? It’s not that I hate what I do, it’s that I, as a living being, hate stress.

Usually, I took the rest of the day off right after dealing with a complex or mundane to refresh the mind. It worked well, but took a lot of time and had a bitter taste of excuse to skip working hours. Today I invented something different for myself.

Here the summary of points that I (and hope you) usually keep in mind when working:

• Focus on the task
• Stop watching the clock
• Keep a clear plan of attack with very small sub-tasks to cross them out as quickly as possible
• Do whatever it takes to protect yourself from getting back (comprehensive tests suite, clear design etc)
• Make a lot of comments to give you a hand if you still need to change something later

And now something new:

• When the task is over, check in the sources, run all tests, and finish anything else that attaches you to the task, and then
• Take a coffee break and detach yourself from it and the results as if somebody else did the job and you are left with an easy part (calling the module, using freshly designed database etc)
• Start (not continue) working refreshed and, possibly, give you some easy and fun tasks to get the happy feeling of great job you always did

These are all simple steps, but I know no one who would follow them. I read many standard advices, like 50 minutes of work / 10 minutes of rest that are far from a silver bullet. They sound like a quick and dirty rule for those (or by those) who don’t really want to think WHY these breaks are important and, what’s more important, what to do during them.

With this last summary I feel I got closer to a better understanding of my own brain and how it works. Now I know how to reset that anxiety and stress to continue moving on without passively waiting for the same effect first.

Hope I induced some fresh ideas and insights. Feel free to share back.

Cheers!

Rails: When an Uninitialized Constant Hits the Vent

Last two weeks I was seeing the production server of one of my clients hit the same error over and over with no visible pattern. This second it works, the next it fails and leaves the Mongrel cluster in an undefined state somewhere between this world and hell.

The error I’m referring to is:

I need to repeat that it comes and goes under some non-obvious circumstances, and is hard to recreate. Fortunately, I found the solution and here’s what it was.

I have a directory hierarchy like below. I’m sure when you see it, it all becomes obvious and simple, but it wasn’t for me at that time as there were many files that I omitted below.

The piece of code in klass1 that failed looks as follows:

Simple, heh.

Utils.rb is a helper module which is included into MyModule, but apparently loaded only when really necessary (it’s the only explanation why it didn’t fail all the time, as you will see). When it is loaded and included, the MyModule::Utils becomes defined, and Utils::NetSession resolution starts to fail. It happens as Rails begins looking for Utils name space from MyModule, finds MyModule::Utils and doesn’t find any NetSession there. That’s pretty much all to it.

The solutions are:

• Either rename utils.rb (which I did in favor of utilities.rb), or
• Use “::Utils::NetSession.new” (which is not safe as one day you can forget about the leading “::”, and get back to roots)

Hope this helps someone like me fighting the way through these extremely infrequent but painful Rails gotchas.

RSpec: Hierarchical Specifications

RSpec is full of great features, but some of them either not very well documented or hidden to a naked eye. No wonder if you never discovered hierarchical specifications.

Traditionally, we write specifications like this:

Now imagine that you have some very similar specs with some common initialization:

You can see that you have common initializations for examples from both specifications and specific initializations for examples from each.

In the previous post I wrote that I prefer not to define helper methods outside the specification definition as they become global and tend to intersect with methods defined in other specs. So, what is the solution?

Assuming that you have a method “authenticate” that you need to call before every example in several specifications, you can define an upper-level specification “authenticated” and group other specs, like this:

Now you have it all in a safe way!

RSpec: Three Things You May Not Know

RSpec is fantastic. It’s so phenomenal that I can’t imagine my development without it anymore. It’s extremely easy to use, fun to write specifications and see how they turn green as you progress. But… at some point, when you have several hundreds of specs, using almost all documented features and excited to max, you may start facing serious problems. They aren’t easy to debug and may lead to a disappointment, unless you are prepared and armed with knowledge.

Load first, then execute. What I discovered was that RSpec loads all specifications upon startup and then executes them one-by-one. It means several things to us, the developers:

• All constants you define in your specifications are global. You will get Ruby warnings on constant redefinitions, but it may not save you from unexpected glitches, when you expect one value, but get a completely different one.
• All methods you define outside your specifications are global. It may affect your specifications in the same way as global constants — the functionality you expect from your helper methods may not be as expected. There are several solutions to this: 1) use modules with unique names to hold your helper methods and include them into your specifications, 2) use specifications hierarchy (my next post is about it) to group specifications that need helper methods.

Partials on Classes and Modules are BAD. It may sound bizarre, but they are. When you stub your Classes and Modules, you do it globally. Whatever you do in one specification or an example is visible in every following. Yes, right, NO ISOLATION. So, when you stub your model’s finders to return a mock, they do return this mock later in other specifications and examples that follow, even though you don’t expect it, and especially when you don’t expect it. It was a huge AHA moment for me.

RSpec loads (runs) specifications in recently-changed last order. It means that it runs specifications you changed last at the end. Now take a break and mull it over. Having everything above in mind, do you still think that you really have a green light? What if you ran you first specification (that you wrote first and never changed since then) after everything else? The only way to know is to try running every specification in your collection last, but of course, it’s not possible. The lack of complete isolation of one spec from another puts a big question mark after “is RSpec as useful as it seems”. My own answer is “yes”, but you need to know about all this to be on the safe side.

To summarize, here’s a quick NO-NO list of mine:

• Never use Partials with Classes and Modules
• Never define constants in or outside specifications
• Never define methods outside specifications

I hope sincerely that this information helps you make your RSpec experience smooth as silk and you’ll avoid the road blocks I experienced during the last few weeks.

Happy Holidays!

BlogBridge: The best version we ever had…

And now, fans, put your hands together! Louder! Louder! I can’t hear you! Last Friday we released the best version of BlogBridge we ever had — BlogBridge 6.0.2. No more no less. It’s the consequential result of polishing, testing, stressing and doing other awful things you don’t want to know.

If you are using a standalone version, odds are you already was invited to upgrade. If it’s a weekly version, it must have upgraded itself automatically. If you never used BlogBridge, well… you are losing your time.

• BlogBridge Official Site
• Download Page

Rails: Haml and Sass

Hey fans of everything concise. My finding of today is Haml and Sass which is a quickly growing replacement for Rhtml (and plain HTML) and CSS. Just check the syntax sample on their main page and admit it, it’s much simpler and cleaner than plain (R)HTML. Everything has a meaning, everything cuts to chase.

Haml can be used with Ruby on Rails as a plug-in that transparently adds the support to your ActiveViews. You simply rename your views from .rhtml to .haml and start deleting redundant code. In case of CSS, you place your .sass in the stylesheets folder and they are automatically compiled on demand. One thing I haven’t figured out yet is whether they do every time, or once per change to save performance.

Haml and Sass are also used in the StaticMatic toolkit, which is exactly how I discovered them. The toolkit lets you put together static sites lighting fast. You simply write your pages in Haml, model your stylesheets in Sass, preview and do a final build. As the result of building you get a bunch of little cute HTML files and CSS stylesheets ready for upload to the site. If you, like me, still like static sites and want to save time on bringing them up and maintaining, it’s your choice.

Let me know what you think. A couple of lines is fine.