In what circumstances should I use instance variables instead of other variable types?

In general an instance variable is local and persisted inside an instance of an object, whereas a local variable is only local and persisted inside a function/object/block scope. For instance:

class User  def name    @name  end  def name= name    @name = name  endenddef greet user  name = user.name || 'John'  p "Hi, my name is #{name}"enduser = User.newgreet user=> 'Hi, my name is John'name=> NameError: undefined local variable or method 'name' for main:Objectuser.name = "Mike"greet user=> 'Hi, my name is Mike'@name=> nil

In the greet function name is a local variable that is only defined within that function. The name variable is set on the first line on the function, name = user.name || 'John', but its value is not persisted outside of the function. When you try calling name you get a NameError because name has only been defined as a local variable within the greet function.

@name is local to the user instance of the User class. When you try calling it outside of that context you get nil. This is one difference between local and instance variables, instance variables return nil if they have not been defined, whereas local non-instance variables raise an Error.

Notice that both variable types are local to a specific context though. @name is defined within the user instance, so when you call user.name you are calling the name function in the user instance, in which @name is defined. name is only defined in the greet function, so when you call p "Hi, my name is #{name}" you are able to get a value for name because you are within the scope in which it is defined.

@Pan's answer gives a good explanation of the difference between them.

In general (in pretty much any language) you want to define variables in the smallest scope required. So if you don't need something to be persisted across function calls, then make it local.

If you need a variable to be persisted across function calls, but only for a particular class instance, make it an instance variable.

If you need something that is shared between every instance of that class, then use a class variable, however the need for this should be somewhat rare, so think carefully whether you really need a class variable.

(Disclaimer: I've only played with Ruby for about 2 weeks, so this is mostly a language agnostic answer, but I'm pretty sure it applies to Ruby. Feel free to correct me if I'm wrong.)