Tag: best practice

Sometimes you have to construct at date at runtime with part of the date based on user input. Like when you have to summarize transactions for a given year.

Ax has a built-in function for this but all too often I see people resorting to convoluted string conversions to achieve the goal. Please don’t, it’s harder to read, more error prone and less efficient. Use mkDate() instead.

So instead of writing something like this:

static void Job1(Args _args)
{
    int givenYear = 2009; // Value acquired somewhere outside the method
 
    date fromDate, toDate;
    ;
 
    fromDate    = str2date("1/1/" + int2str(2009), 123);
    toDate      = str2date("1/1/" + int2str(2009), 123);
}

Write this:

static void Job1(Args _args)
{
    int givenYear = 2009;  // Value acquired somewhere outside the method
 
    date fromDate, toDate;
    ;
 
    fromDate    = mkDate(1, 1, givenYear);
    toDate      = mkDate(31, 12, givenYear);
}

To me, the most important advantage of mkDate() is clarity. Using string conversions distracts from the actual task of constructing a date. Additionally because all arguments to mkDate() are integers it’s easy to do input validation or build a whole bunch of date values in a loop, e.g. every first of every month.

This one is for all those who are new to X++ development. When learning OO programming we’re told that encapsulation is important. Data members (variables) should be hidden and any access should go through methods. Then the typical combination of getters and setters is introduced. You’re supposed to write methods for each thing you want to expose: getSomething() and setSomething(someValue).

In X++ we do this too… with a twist. For starters, all data members of a class (variables in the ClassDeclaration) are protected. So only the class itself and subclasses can access them directly. This means X++ forces you to write methods to access data from outside the class hierarchy. Unlike other mainstream languages such as Java, C# or C++ there is nothing you can do about it. Keywords such as private, protected or public are simply not allowed in a ClassDeclaration.

And there’s more, there are no getters and setters either. It’s not that writing getters and setters is impossible, it’s just not the way things are done. Everything is rolled into a single method, with a name starting with parm. Sometimes they’re called property methods or parm-methods.

A typical example looks like this:

CustAccount parmCustAccount(CustAccount _custAccount = custAccount)
{
    ;
    custAccount = _custAccount;
    return custAccount;
}

It may look confusing but it is actually quite simple. If you use it as a setter, the new value is passed to the object’s data member (custAccount) and the return value is never used. When used as a getter, _custAccount gets the current data member as a default value and this value is eventually returned.

The important thing is that you can use it just like getters and setters you might know. Instead of getCustAccount(), use parmCustAccount(). Instead of setCustAccount(‘1234’), use parmCustAccount(‘1234’).

I recommend you do it this way for any new classes you create. This is something I need to point out in code reviews with new X++ developers all the time. You could argue that the function does two things and in theory it should only do one thing. That’s true. However, this is a minor offense that will not make or break your application. Adhering to the existing code style is important too. Being consistent improves overall readability and usability of the code. When in Rome do as the Romans do.

When you’re creating a new base enum consider using multiples of 10 for values. This makes extending enums a lot easier, especially if it indicates some kind of status. Those of you who once programmed in BASIC, or any other language with line numbers, can probably guess where I’m going with this. My apologies for any painful flashbacks this may trigger.

Suppose you’re creating an interface with another system. It turns out you need a new enum, MessageStatus. Values are assigned automatically, so Received = 0, Started = 1, Processed = 2, and Archived = 3.

Of course, at some point you need to do different things depending on the status. Let’s say you have written this function.

boolean isOpen(MessageStatus _status)
{
    return _status < MessageStatus::Processed;
}

This is a simple way to indicate at which point the message is no longer considered open. Standard Dynamics Ax contains similar examples, e.g. with the inventory status (StatusIssue and StatusReceipt).

Your message handling system goes live and works perfectly. Users are happy, birds are singing, the sun is shining.

After a while users decide they need a verification step before moving to Started. You extend the enum and end up with MessageStatus::Verified = 4. And now things are broken. Verified messages aren’t handled correctly.

You need to check all places where the status is used. You run across the isOpen() method and change it.

boolean isOpen(MessageStatus _status)
{
    return _status < MessageStatus::Processed || _status == MessageStatus::Verified;
}

Not so readable anymore but it works. For now. Things can get out of hand quickly if more than 1 status is added.

This could have been avoided from the start if the enum elements were assigned specific values.

Adding a new step somewhere in the middle is easy. Create Verified with value 15 and isOpen() doesn’t need to be modified.

Now you may think this is a great idea (It is. Thank you.) but don’t go changing all your enums now. Changing values means you also need to modify all fields that use it, as they still contain the old numbers. This is the reason you need to think about enum values in advance. Once a system is deployed, it’s usually better to leave these things as they are to avoid even more trouble.

In practice starting with multiples of 10 is enough to deal with any reasonable modifications. I have yet to run into a situation where a gap of 9 values isn’t enough. Unfortunately standard Dynamics Ax enums have continuous values starting at 0. If you need to insert something in between you still have to check all code that covers a range of enum elements.