Return" in TorqueScript

#1 Return means that you exit the function with the stated variable. For example, you could make a function that returned the color of a ball:

%ballColor = %ballInstance.getColor();

...

ball::getColor()
{
while (1==1)
{
if (getRandom(1,2) == 1)
{
return "red";
}
}
}

The loop will continue as long as 1 equals 1, but, if the conditions for the if statement is true, it will exit and return "red" to the variable %ballColor.

Where ballInstance is a object of the datablock(think class) ball.
Note: i have not tried this, since infinte loops is a bad practice =) But im pretty sure the return statement would break the loop

#2 Oh, I get it now. But what about the brackets? Why are there 3 of them at the end, and multiple ones within others?

#3 There are a couple of very basic "starter articles" on general programming principles and practices located at our TorqueScript Overview on the Torque Developer's Network.

I'd suggest you take a look at the entire article (including linked articles), but the Programming Basics article answers that question.

#4 Making indentions in code is a helpful way to keep everything clean and orderly.
Lets rewrite the function like this:

function sign (%value)
{
   // determines the arithmetic sign of a value
   //
   // PARAMETERS: %value - the value to be analyzed
   //
   // RETURNS: -1 - if the value is negative
   // 0 - if the value is zero
   // 1 - if the value is positive
   //
   if (%value < 0) // is it negative?
   {
      return -1;
   }
   else
   {
      if (%value == 0) //is it zero?
      {
         return 0;
      }
      else
      {
         return 1
      }
   }
}

Now it's easier to see why there's three closing brackets.

As a personal preference, I normally indent code inside "{}" by three spaces. It just helps keeps things tidy.

#5 In most IDE (Integrated Development Environments), there are commands for jumping from one brace/bracket to the other one. For example, in CodeWeaver, the shortcut is control-], I believe. The indentation level is also shown graphically (with a light gray vertical line).

I would always put a "return" statement in any method that returns a value, even though TorqueScript will do a default return if you don't specify it manually. I feel that this is confusing. Code is said to be "written once and read many times" so it is useful to write it to make it as clear as possible what your intention actually was. That makes it easier for someone else to come along after (even yourself after 6 months) and see at a glance what the code does - just in case it isn't doing the correct thing.

In TorqueScript, these two functions do the same thing:

function get1()
{
   %xxx="1"; // returns last string assignment if no specific return
   %zzz= 2;
}

function getOne()
{
   return "1";
}

I think the second one with the specific return command makes the intention of the programmer clearest and easiest to read quickly.