Understanding Your Code

ryanb · 2006-09-02 18:07:05

For every programmer there comes a time when he copies and pastes code from some external source into his project, guesses what's wrong, and blindly hacks away at it until it starts working. He has no idea why or how it works because he doesn't fully understand the code. This is common for beginners, but experienced programmers are sometimes caught doing the same thing. The result is ugly code which will cause problems throughout the entire project. It will continue to break with every related change - and he doesn't know why.

Take a look at the code you wrote (or copied and pasted) this past week. Do you understand every line? What is actually going on behind the scenes? If you do not understand every single line, I encourage you to research what that piece of code is doing.

Learn the Language

If the line you don't understand has some Ruby syntax that you aren't familiar with, break out that Ruby book and research it. Here are some common areas that beginners struggle with because they don't understand that particular Ruby feature:

Code : ruby - fold - unfold

@some_variable # research instance variables
:some_symbol # research symbols
prices.collect! { |p| p + 100 } # research blocks
@a, @b = a, b # research multiple assignment

If this is where you are struggling, I recommend you take some time to learn Ruby on its own.

Know the Variables

Make sure you know what every variable is. Does this variable contain an Integer? A String? An ActiveRecord instance perhaps? If you aren't certain, use the class and inspect methods to find out:

Code : ruby - fold - unfold

some_variable.class # returns the class of that variable
some_variable.inspect # returns the contents of that variable as a string (you may want to try to_s as well)

I usually call these from a breakpoint, but you can output the contents to the view, to the log, raise an exception with them in it, etc.

Find the Method Definition

Most of the code I don't understand involves a method call. What is that method actually doing? Usually the easiest way to find out is search the Rails API and the Ruby documentation. Just scroll through the alphabetical list of methods until you find that call.

Sometimes there's more than one method with that name. For example, there's four "pluralize" methods in Rails. Which one should you look at? Sometimes this takes a bit of guesswork. If I'm calling the method in the view, then it is probably the one in the ActionView module. If I am calling the method on a string, like "friend".pluralize it is probably in the ActiveSupport module because that is filled with extensions Rails makes to the core Ruby classes.

It's better to have more than one method in the docs than no method at all, but unfortunately that is sometimes the case. If the method doesn't exist in the docs, first make sure the method isn't inside your own code or in a 3rd party plugin. Next ask yourself if it is being generated by some other method. For example, has_many generates several methods related to fetching and setting the collection. If you still cannot find the method definition, it is time to look in the source code. Browsing the Rails core source can be difficult at first, but you learn your way around it after a while. If you cannot find the method definition there, or cannot understand it, you can always post the question on these forums and we can help you.

Improve the Code

Now that you understand the code, don't just leave it at that. When you come back to the code in a couple months, you may be left in the same boat of not understanding it. You may be tempted to leave a comment explaining what the code does, but before doing that, try to improve the code itself.

Often if you wrote the code without understanding it to begin with, there is a better way to do it, or maybe the code isn't even necessary. If you cannot find a better way to handle it, try to make the code more readable by renaming variables and methods or moving the confusing code into a new method - giving the method a name which explains the code.

Conclusion

Every time you write a piece of code, copy and paste, use a code generator, etc. ask yourself if you understand every line. If you don't understand it, research it before continuing. This can be tedious, but I guarantee it will pay off. You will have a better understanding of the entire application, you can catch and fix bugs faster, and you will even enjoy programming more. Trying to hack together code which you don't understand can be very frustrating - especially when you have to go back to it 3 months later because of a bug.

I hope you found this useful.

Last edited by ryanb (2006-09-02 18:24:34)

Adam · 2006-09-02 18:31:04

Thanks Ryan - thats good advice for people new to programming and it applies to every language - Ruby/JS/CSS/PHP etc...

Kelli · 2006-09-02 19:12:43

shadow wrote:
Thanks Ryan - thats good advice for people new to programming and it applies to every language - Ruby/JS/CSS/PHP etc...

Indeed.

I think it's a trap we've all fallen into at one point or another, thinkingn it will be quicker to get things done. In the end all it does is slow us down, though, because we don't learn anything from it.

This is something I'm really trying to avoid with RoR and instead I'm just picking through writing my code one line at a time and loving it. It's fun to make all of those little discoveries for yourself, particulalry in RoR because of the way the language/framework works.

plaxdan · 2006-09-21 13:27:13

Check out "Ruby for Rails" by David Black for developing a deeper understanding of your code:

http://tinyurl.com/j8qke

Dieter Komendera · 2006-09-21 13:30:30

I can recommend the book (Ruby for Rails) too. I've read it myself some weeks ago.

cwd · 2006-09-23 04:43:53

I know in Rails we're not supposed to need debuggers cuz we write such beautiful code, but your post points out the fact that we often aren't working with our own code. If you're struggling with what a certain code path does, consider ruby-debug. It's far better for code path inspection than breakpointer because you can step and examine state, then step some more. I still tail the logs as my primary methodology, but when I get really-really stuck, this is the best tool I've seen for Ruby.

http://www.datanoise.com/articles/2006/ … ruby-debug

Sorry, no GUI...

darrenemo · 2006-11-02 03:00:13

Sweet article! Ill have to try this since i'm starting RoR

#1 2006-09-02 18:07:05

#2 2006-09-02 18:31:04

Re: Understanding Your Code

#3 2006-09-02 19:12:43

Re: Understanding Your Code

shadow wrote:

#4 2006-09-21 13:27:13

Re: Understanding Your Code

#5 2006-09-21 13:30:30

Re: Understanding Your Code

#6 2006-09-23 04:43:53

Re: Understanding Your Code

#7 2006-11-02 03:00:13

Re: Understanding Your Code

Board footer