RCR 185: @@_classInstanceVar and @_restrictedInstanceVar

Prevent @instanceVariable initialization bug by renaming @classInstanceVar to @@_classInstanceVar.

Introduce @_restrictedInstanceVar to keep the meaning of added underscore consistent.

Current @classInstanceVariables confuse the programmer due to identical naming to a normal @instanceVariable, especially where the nubie mistakenly puts an initialization of an @variable outside of an instance method (making it a @classInstanceVariable instead of what they assumed would be a normal @instanceMethod).

# probable initialization bug gets introduced in this code
class Foo
  @a = 123   # (1) class instance var initialized
  def foo
    p @a     # (2) 'normal' instance var accessed ...nil not 123
  end
end

Use modified syntax @@_classInstanceVariable instead of @classInstanceVariable. This means that @variables will only be seen in instance methods.

Add syntax @_restrictedInstanceVariable, meaning an instance variable that is not accessible to subclasses. This is something Matz is already considering for Ruby 2. This is included in this proposal to ensure consistent meaning for the adding of a trailing underscore to the @ or @@ prefix (meaning "internal use" or "hidden").

@@classVariable
     * one value shared by all instances of the class
     * visible in instance methods
     * acts like a global variable for the class/module

@@_classInstanceVariable    #<=-modified syntax
     * instances of the class each get their own value to use
     * not visible in instance methods
     * could think of it as a "scratch variable" for use by class methods
     * think of underscore as meaning "internal use", "hidden"

@instanceVariable
     * can be accessed by subclasses

@_restrictedInstanceVariable    #<=-new syntax
     * not accessible by subclasses
     * think of underscore as meaning "internal use", "hidden"

Note that (with the renaming of @classInstanceVar to @@_classInstanceVar) @variables cannot be initialized or used outside of instance methods, and should give an error message like "an @variable can only be used within instance methods" if such use is attempted.

Think of @@ meaning "used in class body and class methods"
Think of @ meaning "used *only* in instance methods"
Think of underscore as meaning "internal use", or "hidden in some way"

class Foo
  # not allowed - use a @@_classInstanceVariable here instead if 
  #   that is the intention
  # error message should say something like 
  #   "@variable must be initialized within an instance method"
  @variable = 0    #produce an error message

  # initialize a class variable, accessible within both 
  #     class methods and instance methods of the class
  @@exampleClassVariable = 880

  # initialize a class instance variable,
  #     not accessible by instance methods
  @@_exampleClassInstanceVariable = 770

  # class method
  def Foo.setExampleClassVariable(value)
    @@exampleClassVariable = value  
  end

  # another class method
  def Foo.setExampleClassInstanceVariable(value)
    @@_exampleClassInstanceVariable = value  
  end

  def initialize
    # initialize an instance variable, accessible within
    #   instance methods of class and subclasses
    @exampleInstanceVariable = 30

    # initialize a "restricted instance variable", 
    #     not accessible by subclasses
    @_exampleRestrictedInstanceVariable = 20

    # modify a class variable
    @@exampleClassVariable += 1
  end  
end

Advantages:
Prevents the @instanceVariable initialization bug.
Clarifies where @@ and @ are to be used in the code.
Class body and class methods only have @@ or @@_ in them.
All @ vars are initialized and used within instance methods.
@@_classInstanceVariables typically not used much, so uglier is better :D

Disadvantages:
Existing usage of @classInstanceVar will need renaming to @@_classInstanceVar, although the disallowing of "@variables" in class body and class methods will show what variables need to be renamed at parse time.

Changes in language.

  @@_@classInstanceVariable
 "@@    associated with class", and _also_ <br>
 "  _@  associated with an instance: an instance of a class in this case"