Ruby arrays with basic math

[trogluddite]

Interesting responses, and I don't disagree with anything that's been said. I think that Ruby was an excellent choice for a scripting language to embed in FS and, as indispensable as API docs like ruby-doc are, I don't think they're enough on their own - the FS docs certainly do need to show some worked up examples, not just give you a list of method signatures.

My point was a bit more subtle than that, and it's not about treating style-guides as prescriptive rules like a "grammar-nazi" moaning about split-infinitives (BTW: this is what some linguists call a "zombie rule": Trekkies will be glad to hear that "to boldy go" is perfectly correct English grammar!). There are two reasons why we don't all write everything in machine code like in the early days of computing. Most obviously, because it makes writing working code a lot easier! But high-level languages aren't just about telling the computer what to do; they're also a way to communicate with other coders - maybe including your future self when you revisit a project from years ago.

For example, Ruby itself doesn't care what you call your variables, method names, classes, or anything else. But, by thinking a little harder about how you name things you can make your code tell a story which anyone who understands the syntax of the language will be able to read. A good bit of advice I once read was this - if you feel you need to add a comment to describe what some code is doing, first think about refactoring the code so that it describes itself...

Code: Select all

def init
  @data = [ ["Foo", 1.99], ["Bar", 0.49] ]
  @sum = 0
end

def add p, q = 1
  @sum += @data[p][1] * q
  output("Added: #{@data[p][0]} * #{q}")
end

## OR ##

def init
  product = Struct.new(:name, :price)
  @products = [
    product.new("Foo", 1.99),
    product.new("Bar", 0.49)
  ]
  @total_cost = 0
end

def add_to_basket(product_code, quantity = 1)
  product = @products[product_code]
  @total_cost += product.price * quantity
  output("Added: #{product.name} * #{quantity}")
end


An exaggerated example, for sure; but with the second version, if I had to fix a bug where customers were being charged incorrectly, it's obvious where to look, even if I've never seen this code before. Even if you don't know Ruby, you can probably make a fair guess at what's going on.

The example of parentheses around method arguments is both practical and aesthetic. There are situations where not being in the habit of doing it can result in code which parses a bit ambiguously - there's even a situation where code blocks made with "do...end" will behave differently than those made with curly-brackets. If you get into the habit of using them, you'll never end up with this kind of hard-to-spot bug in your code.

A bit more subjectively, parentheses around arguments, and using lower_snake_case for methods/variables and CamelCase for class/module names, make the code easier to read - the "kind of thing" which a token represents stands out more (especially for colour-blind coders!) For the kind of short methods you might start out with, it doesn't make a lot of difference; but once you start writing more complex code (and especially if you're going to be sharing it), readability can make a significant difference to how easy the code is to work with. This is why style-conventions can be useful, even though you don't have to be a slave to them.

And I've always felt that these aspects of coding should be learned as early as possible. Human beings get into bad habits very easily! As API documentation, the User Guide examples are fine. But they're also supposed to be a learning resource for novice programmers - especially as FS is now primarily being sold as an educational tool. Getting into useful habits as early as possible makes the rest of the learning process easier.

It's just an extension of what I've always said about using modules wisely, naming all of your inputs/outputs, etc. in schematics; so that they're more easily understood (especially if you're asking for help with them!) Spogg routinely uploads excellent examples of this, and likewise, I try to always have the same things in mind in my Ruby code. A re-write of the User Guide examples isn't essential, but it would encourage this kind of thinking, IMHO.

[Spogg]

... maybe including your future self when you revisit a project from years ago...

I think this is the most appealing reason to stress to people what you said here.

Sometimes I look back at my earlier stuff and think “WTF?”

It’s mainly YOU, as a developer, that benefits in the long run. This rather selfish stance will of course also benefit others who wish to learn.

And I can confirm that I boldly went.

Cheers

Spogg