Menu
Buy
0

Athom Blog

The official blog by Athom, creators of Homey

Athom Academy #1: Design by contract

Posted on August 8, 2018 in Athom Academy

Welcome to the Athom Academy! This is where we, the creators of Homey, share our knowledge of software development with you. Notepad ready, pen in hand, text editor open? Here we go!

Hey there, welcome to the first of many blogs in the Athom Academy series. In these blogs we’ll share our knowledge of software development with you. Hopefully you’ll learn a thing or two from this series along the way. At Athom we always try to learn from our own mistakes, we’re honest with each other and share our opinions directly. This has personally helped me a lot in my development as a software engineer, let’s hope it will do so for you too.

Allow me to briefly introduce myself. I’m Matthew, I study software engineering in Enschede, The Netherlands. I’ve been working for Athom for the last 6 months. Furthermore I’m a typical nerd, playing D&D is not unknown to me, tinkering with electronics isn’t either, developing software as a hobby? Hit me up any day.

Why did you decide to do this series?

What I’ve noticed during my bachelor however is that it doesn’t teach you everything. I came in at Athom relatively inexperienced. I believe I had about a year of professional experience. This meant that for the first two weeks or so I was completely lost in everything that happened around me. For example: Homey has an SDK that comes with documentation which is great. What isn’t great however is that my bachelor often gives us projects to build from the ground up, guess what? That rarely happens in real life. So reading, then understanding, then rebuilding old code in an unknown system is hard. All the while you need to pick it up quickly as well.

This experience, along with the realisation that our colleagues often left better than when they arrived has led us to this point.

The Athom Academy blog series will dive into topics we feel are important to software engineering in general. Besides that we’ll try getting you up to speed with all technologies within Homey as well!

Core concepts to quality code

The first few blogs in this series will be dedicated to some core concepts of software engineering that’ll help make you life easier while developing. To those of you that have had formal education they may seem obvious, to those of you who haven’t they’ll most likely seem like alien concepts at first. We’ll try to strike the right balance between being understandable for beginners and learning new tricks to the experienced developers.

Design by contract

First topic! Are you just as excited for this as I am?

Design by contract sounds boring doesn’t it? It sure did to me at first, I thought some boring management person would come down to me and give me exact specifications as to what I could build. I was horribly wrong back then, in truth design by contract is a tried and tested software design approach.

But what is design by contract? The concept is actually pretty simple. Imagine two parts of a  simple system to calculate the wages for employees of a business. 

Part 1: An Employee class, it stores the age, years of employment at this business and years of experience in total.
Part 2: A simple calculations class, which keeps some calculations, for example for wages.

So inside the calculations class we define the following function:

Clear function name: check,
Clear parameter naming: check,
Uses all parameters: check

In essence this could be regarded as a quality piece of code by the standards above, however is it safe?

Long story short, no. There’s a few cases that this function doesn’t keep in mind, like what happens when an employee’s age is 0? Does that employee suddenly get €21,60 less in wages? But that’d mean their wage could become negative, alongside the legal hassle of having an infant on your payroll.

So how can we fix this? One solution would be defensive programming, another one which increases performance a little is design by contract. Design by contract is the act of designing software in which each function has a clearly defined input it expects and an output it will return. Functions that will call upon each other will have to obey to the input specifications if they want correct output. Basically you can summarise this into one sentence:

“If you do your job correctly, then I’ll also do mine correctly, I’m not here to fix your mistakes.”

These specifications are called contracts, hence the name design by contract. You enforce these contracts by having assertstatements in place during development and testing. These assertstatements are often automatically ignored or compiled away when you ship or compile your software using the production flag appropriate for that platform.

“What does that whole ignoring deal matter anyway?” I hear you ask. Well Homey whilst being awesome is still small and passively cooled. This meant we couldn’t put a giant processor in there as it would overheat. Ignoring the assert statements in production means we save some performance. We’re not checking all the values every function call. Instead we rely on the system to be correct itself, as proven during development and testing.

As a non-Homey-related-note here: imagine having millions of requests every hour. Now imagine doing 7 unnecessary checks on all of those requests. Sooner or later you’re going to be sorry for your own wallet when you see that server bill.

What does this mean for our little bit of JavaScript up there? We can rewrite it to the following (JavaScriptdoes not natively support assert, however there is an awesome library: aspectJS, link below):

The AJS_Validatorstatements inside the calculateWagefunction guarantee that our calling arguments are in fact numbers. The defined validation definition below has been linked to the this class by its first parameter, the second parameter defines the definition on how to validate, which includes first the method names of the functions it applies to and second the definition for how to validate when these functions are called.

This disallows you from entering a negative, 0 or lower than 16 value as age for example.

The second and third argument, being the years of employment and the experience aren’t allowed to be negative values, however they can be 0, for someone who has just started their career for example.

In production all of these validations will be ignored! This means that in production the system isn’t as harsh on the errors as it is during testing and development. The idea is that you will find most bugs and fix them during testing and development, so that the production system is reasonably guaranteed to be bug free.

This does however mean that calculateWageIsn’t going to fix any of the input mistakes it may receive from the system calling it, which is correct. The responsibility of checking and fixing the input data is not given to the calculateWagefunction but to the system calling it. This keeps code clean, easy to maintain and it speeds up bug hunting.

That’s it for this one, I hope you’ve learned something by reading this blog! You might’ve even enjoyed it, or at least I’ll imagine so for my own sanity and happiness. 

Do you have any feedback? Did you like this blog? Do you have ideas for future topics? Feel free to contact me at matthew@athom.nl.

AspectJS to be found here: http://www.aspectjs.com

Back