{"id":2782,"date":"2022-03-17T08:51:39","date_gmt":"2022-03-17T12:51:39","guid":{"rendered":"https:\/\/blogs.mathworks.com\/developer\/?p=2782"},"modified":"2022-03-17T08:51:39","modified_gmt":"2022-03-17T12:51:39","slug":"using-custom-classes-to-convey-intent","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/developer\/2022\/03\/17\/using-custom-classes-to-convey-intent\/","title":{"rendered":"You’ve Got Mail"},"content":{"rendered":"

Let’s send some emails!<\/a><\/h4>

Imagine you write a function that sends an email to a customer. Your initial function call might look like this:<\/p>

  sendEmail(emailAddress,firstName,lastName,bodyText)<\/pre>
Having 4 inputs to our function is fine, but if we need to add more customer details it becomes difficult to manage. When working on software projects, we find that certain variables tend to be grouped together. In our case, “first name”, “last name”, and “email address” represent a customer. We might also have “name”, “description”, and “price” to represent a product, or “customer”, “product”, and “datetime” to represent an order.<\/p>
So let’s group our first 3 inputs into a single variable. The simplest way to do this is with a struct<\/a>:<\/p>
  customer = struct(\"FirstName\",firstName,\"LastName\",lastName,\"Email\",emailAddress);<\/pre>
Our function call then becomes:<\/p>
  sendEmail(customer,bodyText)<\/pre>
The advantage of this is that we can now pass around all the information related to a customer as a single variable. If their postal address is added to the struct, it’s automatically available for us to use in our sendEmail<\/tt> function.<\/p>
What’s in a customer?<\/a><\/h4>
A disadvantage arises when a new developer (or you several weeks from now!) looks at this function again. What exactly is in<\/i> the “customer” struct? Is the field for their first name called “FirstName” or “Firstname” or “firstname”?<\/p>
If you try to access a field that doesn’t exist, you’ll get an error, but if you set a field that didn’t previously exist, it will be automatically added to the struct. Maybe you can work out the correct names from the existing code, assuming it’s not too long or complex. Otherwise, you’ll have to run a test (because someone has written a test<\/a>, right?) and see what is provided to the function at runtime.<\/p>
With a customer, we can at least take an educated guess as to the contents. If a more generic name is adopted (“data”, “metdadata”, “info”), it can be impossible.<\/p>
This lack of clarity wastes developer time over and over again, and can cause subtle bugs that are hard to track down.<\/p>
What’s a valid customer?<\/a><\/h4>
To address this, we could define validation on the customer<\/tt> input: we want to make sure that we have a scalar struct with the correct field names, that the data types are correct, and that any other validation rules are met. For example, that the email address is always of the format “*@*.*” .<\/p>
Managing this can be complex and laborious. If you’re not careful, it leads to scattered code that repeats the validation and that is difficult to read. Furthermore, can we guarantee<\/i> that all such “customer structs” will always be valid? No – it’s possible for us, or another developer, to create an invalid customer struct and we won’t know about it until we run our validation again or the code errors.<\/p>
This forms a second source of bugs – data that is not in the expected format. Common issues include variables that are empty but shouldn’t be, or a cellstr that should be a string array.<\/p>
What do we need from a customer?<\/a><\/h4>
There are operations that we frequently need to perform on our customer struct. For example, constructing the customer’s full name from their first and last name:<\/p>
  fullname = customer.FirstName + \" \" + customer.LastName;<\/pre>
Writing this code each time we need the full name either leads to code duplication (and a high likelihood of inconsistency), or a function that’s divorced from its data and potentially hard to find.<\/p>
Define a class instead<\/a><\/h4>
Instead, we can define a class<\/a> for our customer! Doing so will bring the following advantages:<\/p>
Functions that use the customer class only need one line of validation in the arguments block – the required class. The validation line tells you exactly what the input is, and you can immediately hit Ctrl+D<\/tt> to go to the class definition. It forms a clear contract between the calling code and your class.<\/p>
The properties block tells you exactly what properties all<\/i> objects of that class will have. The validation for each property makes explicit what each property will contain, it can set default values, and it guarantees that all objects of the class will be valid.<\/p>
Dependent properties can be added to give you derived information without having to poke around the internals of the object (hello encapsulation<\/a>!); tell the object<\/a> what you want it to do, don’t ask for the individual pieces of data. Other functionality related to the class can be added as methods.<\/p>
Make your class work with arrays<\/a><\/h4>
Custom classes really begin to shine when you make them array compatible. Rather than having a<\/i> customer or an<\/i> order, you can have an array of customers or orders and perform operations on them in one go. This native array handling is one of the unique features of MATLAB and removes the need for a “collection” object like you might have in C.<\/p>
An array-based method I almost always add is table<\/tt>. table<\/tt> transforms an array of objects into a standard MATLAB table<\/a>. It allows you to easily see the entire contents of the object array and perhaps to write the data into a uitable<\/a> for display or to a spreadsheet<\/a> for reporting purposes.<\/p>
So why go to all this trouble of creating a custom class just to turn it back into a generic data type? The crucial difference now is that the table is derived<\/i> from our custom class which handles all the validation and calculations; the table is not the source of truth.<\/p>
Code example<\/a><\/h4>
Below is example code showing what a customer might look like when implemented as a class in MATLAB:<\/p>