5 mistakes that make you look like a Rails n00b

Update: As pointed out in the comments & elsewhere, these bad practices are common to those learning many (most?) programming languages, and are not necessarily specific to Rails. My experience is just with teaching Rails, where I see these often, so that’s the context in which I can assert that they are common. But if these hit close to home, know that it isn’t just you! Coders everywhere need to learn past these and similar hurdles.

There is a lot to learn when you first dive in to Ruby and Rails. Here are some things you can pick up (easier than meta-programming!) that will keep you and your code from looking n00b-tastic.

Does it really matter?

You may think that no one will ever look at your code or watch your development process. You don’t plan to open-source it, and expert coders aren’t hanging out on your couch looking over your shoulder. I’m here to tell you, stop thinking this way. One very important coder will be accessing your project regularly: you. A few simple habits can dramatically reduce how much time you waste troubleshooting and banging your head against simple things.

N00b mistake #1: poorly-indented code.

I do a lot of one-on-one training with people at various levels of Rails proficiency, and over and over I see things like this:

Ruby is not whitespace-sensitive, so it lets you get away with this…but that does mean you should. As a wise man once said, it’s a trap!

This hurts you in many ways. Structure is lost. Flow is harder to follow. Your code is no longer scannable. Bugs are easily introduced if a change is made in the wrong block. And perhaps worst of all, it causes degenerative issues. The disorder can spread. Code that looks bad is more likely to be modfied in careless ways. Bad whitespacing is the gateway drug, leading to ugly code.

N00b mistake #2: ignore the output.

Ever run migrations and STILL see that error about a missing field or table? Why isn’t it working? Betcha you tried a lot of other things before realizing that the migrations had failed for some reason, but you missed the error message. I’ve been there, and I’ve seen plenty of my students make similar mistakes. Nearly everything that you do from the console will produce some kind of output, and YOU SHOULD READ IT. Success, failures, deprecation warnings, progress indicators, whatever it is… read it, and try to understand it. It’s there because the process you are running wants you to know, usually for a good reason.

Now, I admit, that learning to read and act on specific error messages takes some practice, but you really should at least know if there was an error. Then you have a hope of googling understanding it. Many times, reading carefully can tell you exactly what the issue is.

N00b mistake #3: bad variable & method names.

Sure, it’s easier to type v1, v2, and v3 for local variables. Yes, the program will work if you name a method `do_thing` or some not-quite-a-keyword term. And it’s easier to eat fast food every night. But it isn’t good for you, and it isn’t good for your code. Programmers can benefit from being lazy, but please try to be the right kind of lazy.

The code you write has the nearly-magical property of being both machine-readable and human-readable. The machine will do just fine with whatever names you pick. Since the choice is left entirely up to you, optimize for human-readability (this applies to nearly all code-level decisions you make). Bad variable and method names obfuscate the meaning of your code, and make it harder to keep track of what you are trying to do, and how you are doing it.

N00b mistake #4: half-assed commit messages.

Of course, the newbiest mistake is using no version control system at all. But not you! You are an enlightened newbie, so you installed git, and you understand the tinker-toy analogy, and you’ve played through some Git Real.

But you still think it is ok to occasionally do something like this:

    > git commit -am "A bunch of changes"

Do so only if you want to delay your departure from the Kingdom of Newbland. Git is a powerful tool, and should be respected as such. Just as clarity in your coding does wonders for protecting your sanity and mental processes, so does clarity in your commits.

There are just 2 rules to follow here. The first is simple: Answer the “why?” question. If another developer (likely: your future self) would someday read this, would they understand your motivation for making this change, and doing it the way you did it?

The second rule is not difficult either: If the code change is more than something trivial, your commit should consist of a title line (less than 50 characters), followed by a blank line and then as much description as necessary to answer the “why?” question.

N00b mistake #5: leave commented-out code in the repo.

Ok, sure, comment something out to see what happens when the program runs without that line. Fine. That’s a reasonable debugging practice. But, please, do not leave it that way. Do not commit it that way. Do not expect others (including, yup, your future self) to understand why it is there, why it is commented out, and what they are supposed to do about it (leave it? fix it? delete it? restore it?). It’s an unsightly mess that reduces clarity and can waste someone else’s time trying to deal with it.

The alternative, of course, is to trust your VCS. Commit it if you want to preserve it, and then remove it, explain why, and commit again. If you need to find it later, you can use this wondrous git command to find it:

    git whatchanged -p --abbrev-commit --pretty=medium

Better yet, put this in your .bash_profile:

    alias gwc='git whatchanged -p --abbrev-commit --pretty=medium'

Then you can see the full history, with changes and explanation messages with a command like:

    gwc app/models/user.rb

See? isn’t that better than ambiguous chunks of grey-out text interrupting the flow of your program logic? Yes. Yes it is.

There they are, five n00b-alicous mistakes you now know to avoid. Hit me with your [least] favorite newbie-isms in the comments, and when you are ready for more great tips on learning rails:

• Check out my September workshop, where I’ll teach you everything you need to know to build deploy your own rails app in less than 8 hours.See Workshop Info
• Or get on the (always spam-free) list for more learning tools & workshop announcements: