Code Documentation

If you are like me, you like your code documented. At least the important parts. Nothing spoils the day as browsing through hundreds of lines of code in effort to remember what was the original idea behind all that mess. Documentation comments help other people to read your code, ease the maintenance, and, if you do it right, even a decent API reference can be generated from them. So, the time has come to give some shape to my random in-code remarks.

Since I intended to use UnityScript and C#, I wondered what documentation generators (à la javadoc) could be employed. Picking the right choice would allow me to use the correct syntax from the start. I've found [1] that Doxygen is a great option for C#. It supports the standard XML-like syntax as well as its own – shorter and better readable in my opinion –, and it's been here for a while (so it's a really mature tool). For UnityScript, the options are not that great, although the YUIDoc is a solid solution that gets the job done.

Handling Errors

What do you think will happen when you throw an exception anywhere in a MonoBehaviour's callback (e.g. Awake(), Start(), Update(), etc.) and never catch it? Well, nothing much. Your callback will return, so the code following after the exception's origin won't get executed, a message will be printed to the log, and that's it. Your application will keep running, all your MonoBehaviours will keep running, and all of your callbacks, including the one that caused the error, will be called again as normal.

If you are like me and prefer to address serious errors in a timely fashion instead of ignoring them, you'll be soon wondering how to change this strange behaviour and stop the execution of your program on a non-recoverable error. After some research, I've found no standard solution, only three workarounds:

1. You can wrap every MonoBehaviour callback in a try-catch block and abort on catch.
2. You can forgo the standard throwing mechanism altogether and call your own routine, something like ThrowException(new Exception()), which will terminate your application. 
3. You can attach a listener to the log and react if an exception is logged. It will work even if the Player log is turned off in Player settings.

The problem with the solution #1 is that it slows down the performance and is cumbersome to implement and maintain – there are dozens of MonoBehaviour callbacks and more may appear in the future. #2, on the other hand, would be cumbersome to use, since it's essentially an error checking system. It would look like this:

class ErrorHandler extends MonoBehaviour
{
  static function ThrowException(_exception: Exception)
  { 
    if (exception == null) {
      exception = _exception;
    }
  }

  static function HasExceptionHappened(): boolean
  {
    return (exception != null);
  }

  static private var exception: Exception;


  function Update()
  {
    if (exception != null) {
      Debug.LogException(exception);
      exception = null;
      Application.Quit();
    }
  }
}

DoSomething();
if (ErrorHandler.HasExceptionHappened()) return;
DoSomethingElse();
if (ErrorHandler.HasExceptionHappened()) return;

Also, you couldn't force 3rd party scripts to use it anyway. The only sound solution seems to be the #3 (see [1] for more details).



What if you wanted to abort? Application.Quit() is great for exiting under normal conditions, but how do you indicate to the outside world that your application didn't finish peacefully? System.Environment.Exit() doesn't work, neither do System.Environment.ExitCode, System.Diagnostics.Debug or System.Diagnostics.Trace methods. The best bet would be to store the return value into a file or a system registry, where it could be acted upon by an error reporter or whatever running in parallel.

Considering the System.Diagnostics.Debug and System.Diagnostics.Trace don't work, asserts are also not available. And the System.Diagnostics.Contracts.Contract.Assert() is too new to be supported. It's easy to implement your own basic asserts though:

[Conditional("DEBUG")]
static public void Assert(bool _condition, string _message = "")
{
  if (! _condition) {
    Debug.LogError("Assertion failed: " + _message);
    Application.Quit();
  }
}

Notice the “DEBUG” constant. It is not set by default, and in Unity you cannot use #define to make pre-processor defines. They are simply ignored. However, you can specify them in “Edit → Project Settings → Player” under “Scripting Define Symbols” for each platform. It is a little clumsy to write and delete them by hand, but the process could be possibly automated by a script (see PlayerSettings.SetScriptingDefineSymbolsForGroup).

Fun Fact: Unboxing in UnityScript

Let's write a code snippet in UnityScript that stores integers and strings in an associative array:

var container = new Hashtable();

container.Add("property1", 5);
container.Add("property2", "text");

var num: int = container["property1"];
print("num=" + num);

Retrieving the int value from the container emits a warning: “BCW0028: WARNING: Implicit downcast from 'Object' to 'int'.” But, since we want to maintain a clean code, how do we downcast explicitly?

This widely spread construct – var num: int = (int) container["property1"] – doesn't work. The operator as doesn't help neither; it only works for reference types. What do we do?

We turn to parsing text. Yes, seriously, the advice you'll get from every corner of the Unity community[1] and the only one that seems to work flawlessly so far is to use parseInt(). That means the value is printed to a string, then parsed back basically to the same value, but assigned a different type. All of this is going on in this short line of code:

var num: int = parseInt(container["property1"].ToString());

It's great we don't have to send it to a Unity server and wait until they parse it for us. Thank you, guys.

At the end of the day, it's a tough decision: Do we live with a log polluted with warnings, or do we parse text back and forth? Do you know of a better option?



By the way, C# has no issues with unboxing. This snippet works as expected:

var container = new Hashtable();

container.Add("property1", 5);
container.Add("property2", "text");

int num = (int) container["property1"];
Debug.Log("num=" + num);