Support

If you have a problem or need to report a bug please email : support@dsprobotics.com

There are 3 sections to this support area:

DOWNLOADS: access to product manuals, support files and drivers

HELP & INFORMATION: tutorials and example files for learning or finding pre-made modules for your projects

USER FORUMS: meet with other users and exchange ideas, you can also get help and assistance here

NEW REGISTRATIONS - please contact us if you wish to register on the forum

Ruby arrays with basic math

For general discussion related FlowStone

Re: Ruby arrays with basic math

Postby trogluddite » Thu May 09, 2019 4:38 pm

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.
All schematics/modules I post are free for all to use - but a credit is always polite!
Don't stagnate, mutate to create!
User avatar
trogluddite
 
Posts: 1727
Joined: Fri Oct 22, 2010 12:46 am
Location: Yorkshire, UK

Re: Ruby arrays with basic math

Postby Spogg » Fri May 10, 2019 7:33 am

trogluddite wrote: ... 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?:lol:

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
User avatar
Spogg
 
Posts: 3318
Joined: Thu Nov 20, 2014 4:24 pm
Location: Birmingham, England

Previous

Return to General

Who is online

Users browsing this forum: No registered users and 44 guests

cron