Naming things in Ruby
Posted: Thu Jan 23, 2014 10:03 pm
Just recently in another thread...
Without just trying it in the Ruby code, not really - but there are a set of simple syntax rules for all of the different kinds of things that we have to dream up names for.
In the following, I've also mentioned 'conventions' and 'style' - these are things which are not strict syntax rules, and often don't get mentioned in Ruby learning books. But the majority of Ruby programmers have agreed over the years to use these guidelines because they make code clearer to read, especially when sharing it with others.
There's a more comprehensive guide to the 'style' HERE if you need some help getting to sleep (NB - jump straight to 'style guidelines', the first half is not so applicable to FlowStone). It's not something to get obsessive about - we don't want to end up like 'C++' coders; spending all our time flaming each other over where to put our {curlies} - it's more impprtant just to be thinking about consistency when coding, so that you aren't wasting time guessing what you might have called something
(The FS parts of Ruby often don't observe the conventions - e.g. "isInMouseArea" instead of 'is_in_mouse_area?" - makes me really, really MAD!
He he).
Anyhow, here's the rundown on how to make sure your variables etc. have valid names...
Instance variables - these are the ones available anywhere in the same RubyEdit primitive (or to a single object when making your own custom classes). Giving an input or output connector on a Ruby editor a label will create an instance variable with that name - but you have to follow the naming rules for this to work.
- Always begin with a single '@' in the code (not used when naming the connector labels on the primitive)
- First character should be a letter or an underscore.
- After that, any combination of letters, digits and underscore.
- There is an unofficial convention that the name should begin lower case, but it's not an essential part of the syntax.
Local variables - retain their values only within the current code block, and are also used for receiving method arguments.
- Must begin with a lower-case letter or an underscore.
- Followed by any combination of letters, digits and underscores.
A 'code block' in this context could be...
- Between the 'def' and 'end' of a method definition.
- The inside of a loop.
- Code enclosed between 'do' and 'end', or inside curly brackets.
Once the 'block' ends, the local variable goes out of scope, and no longer exists. If there's already a variable with the same name outside the block, that variable gets used instead of creating a 'nested' one.
Constants - for values that are set once and then never changed.
- Always begin with an upper-case letter.
- Followed by any combination of letters, digits and underscores.
- It is convention that all letters are upper-case to more easily distinguish constants from class names.
Class/Module variables - available to all objects of the same class. Best only used when absolutely necessary to prevent 'crosstalk' between multiple instances of the same plugin.
- Same as instance variables except that they start with two '@' characters.
Global variables - common to all Rubyedits everywhere. Best only used when absolutely necessary to prevent 'crosstalk' between multiple instances of the same plugin.
- Start with '$'
- Followed by any combination of letters, digits and underscores.
- As with constants, all upper-case is the usual convention.
Method names.
- Exactly the same as for local variables. Ruby is usually pretty good at telling them apart from the context, but it's better to avoid having a local variable and a method sharing the same name to avoid confusion (for the Ruby parser or the programmer!)
- (Optional) can also end with a question mark or an exclamation mark. The convention is that '?' ends a method name that 'asks' a true/false question - e.g. 'contains?", 'is_a?'. The '!' ending is usually used to indicate a method that needs extra care when using it (often called a 'bang method'). Often, but not always, it indicates a method that changes the original object ('self' or 'receiver') rather than returning a new object.
Another common convention, used by all of the 'standard' Ruby methods, is to always use 'snake case' - all lower case with underscores separating words. e.g. 'each_with_index', 'is_a?', 'define_singleton_method'
Class/Module names.
- Must begin with an upper case letter.
- Followed by any combination of letters, digits and underscores.
- By convention a mixture of upper and lower case will be used to tell them apart from constants (in fact, a class name is a constant - just used in a special way). Most commonly, 'camel case' is used - words capitalised, but no underscores. e.g. 'StringFormat, 'GraphicsPath'.
NB) For a bit of further reading (as if that wasn't enough!), the issue of where a variable is available is known as "variable scope" - any 'learning Ruby" guide will have a section about it.
RJHollins wrote:Is there a way to test if a variable name [label] is not acceptable ?
Without just trying it in the Ruby code, not really - but there are a set of simple syntax rules for all of the different kinds of things that we have to dream up names for.
In the following, I've also mentioned 'conventions' and 'style' - these are things which are not strict syntax rules, and often don't get mentioned in Ruby learning books. But the majority of Ruby programmers have agreed over the years to use these guidelines because they make code clearer to read, especially when sharing it with others.
There's a more comprehensive guide to the 'style' HERE if you need some help getting to sleep (NB - jump straight to 'style guidelines', the first half is not so applicable to FlowStone). It's not something to get obsessive about - we don't want to end up like 'C++' coders; spending all our time flaming each other over where to put our {curlies} - it's more impprtant just to be thinking about consistency when coding, so that you aren't wasting time guessing what you might have called something
(The FS parts of Ruby often don't observe the conventions - e.g. "isInMouseArea" instead of 'is_in_mouse_area?" - makes me really, really MAD!
He he).Anyhow, here's the rundown on how to make sure your variables etc. have valid names...
Instance variables - these are the ones available anywhere in the same RubyEdit primitive (or to a single object when making your own custom classes). Giving an input or output connector on a Ruby editor a label will create an instance variable with that name - but you have to follow the naming rules for this to work.
- Always begin with a single '@' in the code (not used when naming the connector labels on the primitive)
- First character should be a letter or an underscore.
- After that, any combination of letters, digits and underscore.
- There is an unofficial convention that the name should begin lower case, but it's not an essential part of the syntax.
Local variables - retain their values only within the current code block, and are also used for receiving method arguments.
- Must begin with a lower-case letter or an underscore.
- Followed by any combination of letters, digits and underscores.
A 'code block' in this context could be...
- Between the 'def' and 'end' of a method definition.
- The inside of a loop.
- Code enclosed between 'do' and 'end', or inside curly brackets.
Once the 'block' ends, the local variable goes out of scope, and no longer exists. If there's already a variable with the same name outside the block, that variable gets used instead of creating a 'nested' one.
Constants - for values that are set once and then never changed.
- Always begin with an upper-case letter.
- Followed by any combination of letters, digits and underscores.
- It is convention that all letters are upper-case to more easily distinguish constants from class names.
Class/Module variables - available to all objects of the same class. Best only used when absolutely necessary to prevent 'crosstalk' between multiple instances of the same plugin.
- Same as instance variables except that they start with two '@' characters.
Global variables - common to all Rubyedits everywhere. Best only used when absolutely necessary to prevent 'crosstalk' between multiple instances of the same plugin.
- Start with '$'
- Followed by any combination of letters, digits and underscores.
- As with constants, all upper-case is the usual convention.
Method names.
- Exactly the same as for local variables. Ruby is usually pretty good at telling them apart from the context, but it's better to avoid having a local variable and a method sharing the same name to avoid confusion (for the Ruby parser or the programmer!)
- (Optional) can also end with a question mark or an exclamation mark. The convention is that '?' ends a method name that 'asks' a true/false question - e.g. 'contains?", 'is_a?'. The '!' ending is usually used to indicate a method that needs extra care when using it (often called a 'bang method'). Often, but not always, it indicates a method that changes the original object ('self' or 'receiver') rather than returning a new object.
Another common convention, used by all of the 'standard' Ruby methods, is to always use 'snake case' - all lower case with underscores separating words. e.g. 'each_with_index', 'is_a?', 'define_singleton_method'
Class/Module names.
- Must begin with an upper case letter.
- Followed by any combination of letters, digits and underscores.
- By convention a mixture of upper and lower case will be used to tell them apart from constants (in fact, a class name is a constant - just used in a special way). Most commonly, 'camel case' is used - words capitalised, but no underscores. e.g. 'StringFormat, 'GraphicsPath'.
NB) For a bit of further reading (as if that wasn't enough!), the issue of where a variable is available is known as "variable scope" - any 'learning Ruby" guide will have a section about it.
