Skip to main content

Simple code: Contracts

Code works around contracts and contracts should be carefully thought and crafted.

What are contracts


A High abstraction level of contracts for code are API's. They define a interface that is basically a contract that the producer and consumer of the API agree to use to communicate with each other. Two common forms of API's are libraries that are used in code and external API's  that are used via HTTP, RPC etc.

When thinking in a bit deeper contracts consist firstly of functions, methods or external endpoints and secondly of data, more precisely on data models and data types within the models.
 

Defining contracts


Contracts should always be defined with careful thought. I've come accross few times to someone saying that "this is for intenal use only so it doesn't need to defined and/or documented as thoughtfully as a public API would be" but I disagree with that. The same care should be be given to internal and external contracts because the contracts are defined to used by other code and most likely by other developers. Contracts are a key incredient in developer experience.

Tests love contracts


Contracts also work as a base for testing whether it's unit, integration or acceptance testing they are all implemented against a some sort of contract. Without properly defined contracts testing would be nearly impossible because of all the possible variations a badly designed API would enable.

Formats of contracts


One incarnation of data model contracts are schemas. Those who have worked long enough in the industry can remember SOAP, XML Schemas and WSDL, after XML came JSON and *drum roll* JSON schemas that are probably most often seen in Open API specifications. Some of the newer formats for defining contracts for code are e.g. Apache Avro and Protobuf. 

They're all basically the same thing just defined in a bit different format and they all address the same issue of defining a contract of what the input and ouput data must look like and some of the definitions also define transport protocols.

Contracts appear in many ways and the trick is to understand that they are actually contracts. Not just some random bits of code that can be whipped together without a second thought but something that deserves attention.

Next part


In the next part I'll be writing about a special thing, immutability.

Labels:
Location: Espoo, Finland

Popular posts from this blog

Simple code: Naming things

There are two hard things in programming and naming is one them. If you don't believe me ask Martin Fowler https://www.martinfowler.com/bliki/TwoHardThings.html . In this post I'll be covering some general conventions for naming things to improve readability and understandabilty of the code. There are lots of things that need a name in programming. Starting from higher abstractions to lower we need to name a project, API or library, we probably need to name the source code repository, when we get to the code we need to name our modules or packages, we give names to classes, objects, interfaces and in those we name our functions or methods and within those we name our variables. Overall a lot of things to name. TLDR; Basic rule There's a single basic convention to follow to achiveve better, more descriptive naming of things. Give it a meaningful name i.e. don't use shorthands like gen or single letter variables like a, x, z instead tell what it represents, what it does...
Read more

DIY home automation, new generation

I've had my DIY home automation system for controlling outlets and reading sensor data running for about two years now. The system has been working fine and I haven't had any need to touch the code since I added the sensor reading to it, until a few months back. Need for new functionality Few months ago I got a new IoT toy for a lend from a friend until I'd get my own toys, a ruuvitag sensor beacon. Ever since I found the ruuvitag for the first time from kickstarter I had the idea of getting a bunch of ruuvitags and adding their weather station sensor readings as part of my home automation system. The original home automation backend included only tellstick compatible devices and was written in Python, and in my mind it was kind of a hack. The ruuvitag beacons communicate via BLE i.e. Bluetooth Low Energy and that meant that I needed to add functionality to read the beacon data via bluetooth. I found a ruuvitag Python library and initially thought that I'd just...
Read more

Simple code: Unit tests

Unit tests are the developers number one safety net. Let that sink in. This is the number one reason for writing unit tests. Unit tests are written by developers for developers to ensure that the code works as expected and handles happy and sad paths correctly. With enough unit test coverage the tests enable a safe environment for refactoring and rewriting code. Unit test scope Unit test should test a single thing, a method or function call and it should test only one use case within. In other words a unit test should test a function with a single input. This is a important guideline to understand. When a unit test tests a function with single input it makes the test isolated, repeatable and predictable. Example of good tests: @Test fun findsAddress() {   val address = findAddress("Stevens street 35", "Southport", "Australia")   assertThat(address).isNotNull() } @Test fun doesNotFindAddress() {   val address = findAddress("Stevens street 697", ...
Read more