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:
Hello, I’m a student and this site really aided me. I’m motivated! Thanks very much!
Hi! Enjoyed your write-up, thanks!
Wonderful tips. Many thanks for sharing!
#2 is so key. Read the stack trace! So many people gloss over anything longer than a paragraph, missing the critical info about the error. Also, read the brew caveats! brew info [packagename] if you need to see it again.
You realize these “mistakes” have nothing to do with Rails specifically.
Thanks to all you thoughtful commenters, I am realizing this!
I don’t have any experience teaching other languages, so all I can speak from is what I’ve seen un-newbie-fying my Rails students.
#1-3 are rookie coder mistakes generally
#4 & #5 are poor version control practices, which are not remotely limited to newbies. Arguably, they’re only important mistakes if one is developing collaboratively. For that matter, on a private branch it’s a matter of personal taste whether to use meaningful commit messages. Squash, assign one real message, rebase.
Version control is a really useful thing to be doing, but one can be good at coding without doing it this way. Boy do I know lots of seasoned coders who do 4 & 5 routinely.
One red flag I _would_ watch out for: a n00b using `git commit -am`. Many people misunderstand what it means, leading them to either over- or under-commit the extent of changes that belong together. If a git n00b weren’t using `git add` to stage changes, s/he’d bear watching.
None of these show how little/much experience one has with Rails programming. If anyone draws conclusions from these about whether you’re a Rails n00b, that’s their mistake.
Hey, thanks for your comment. Great point on `git commit -am`! It is often misunderstood.
I like your thinking on using squash as well. That’s something I could probably do more of. As it stands, I find it helpful to for my own thought processes to answer the “why” on every commit. Sometimes I’ll be half way through the commit message, but writing it out will make me realize there is a piece I’ve forgotten, or something else that should logically be included.
I would hope, however, that the more experience one has with Rails, the less often we’d see these mistakes.
[...] the items they value the most…time, effort, resources and most of all, money. BroadcastingAdam 5 mistakes that make you look like a Rails n00b | Ready Set Rails There is a lot to learn when you first dive in to Ruby and Rails. Here are some things you can [...]
Nitpick: these won’t just make you look like a Rails n00b, but a total *programming* n00b.
Let’s see if we can come up with a bunch of Rails-specific don’t-look-like-a-n00b tips. Off the top of my head:
- Leaving the default fugly styling.
- Lots of logic in the views. (Okay, that’s MVC-n00b-ish, not all that Rails-specific, but at least a step in the right direction.)
- Reimplementing manually a lot of the “magic” that Rails does for you if you let it.
Your turn!
Thanks for the productive comment! You are right, there are things that are more specific to Rails that could also be addressed. I like your suggestions… Another post is already in the works!
With #4 … what if it only happens … sometimes? ;)
http://www.webpagescreenshot.info/i/422632-911201234809pm.png
Ha! We are all guilty, I’m sure.
These mistakes are not really related to rails … they make you look like a noob in every programming language / framework.
Yeah, these could be applied fairly broadly, but not quite universally. Python requires good whitespace, for example. Objective-C does a great job with descriptive variable/method names, so beginners aren’t as likely to make that mistake.
I work daily with students learning Rails (that’s also the primary audience for this blog), so that was my context for writing this. I’m glad to hear the principles are more generally applicable!
Why specify ruby? these are pretty much universal.
I presume as well that similar things are common in other languages, but I don’t have experience teaching other languages. These are the things I see day in and day out as I’m teaching Rails.
Based on the thoughtful comments here, I’ve considered changing the title, but I don’t want to overstate my expertise. I wanted to write a quick guide for those looking to learn Rails. There may be other more significant mistakes beginners make in other communities.
As a Newbie, I am always browsing online for articles that can aid me. Thank you