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

Simple code: Integration tests

Integration test is something that tests a functionality that is dependant on a external system e.g. a database, HTTP API or message queue. Integration vs unit tests The line is thin in my opinion. The integration part can be faked or a embedded services can be used in place of the actual integration point and with these solutions the interaction with the external system is bounded in the test context and the tests can be executed in isolation so they are very much like unit tests. The only difference with this type of integration test and unit test is that the startup time of the embedded or faked system usually takes some seconds and that adds total execution time of the tests. Even though the total test exection time is longer all the tests need to pass and all the cases need to be covered whether there's external systems involved or not so the importance is equal between the test types. This is why I wouldn't separate unit and integration tests from each other within the co...
Read more

Simple code: Simplicity

Simplest solutions are usually the best solutions. We as software developers work with hard problems and solve a lot of small problems every day. Solving a hard problem itself is a hard job. Though in my opinion it's not enough to solve a hard problem in any possible way but a hard problem should be solved with a simple solution. When a developer comes up with a simple solution to a hard problem then they can declare the problem solved. First a disclaimer. Coming up with a simple solution to a hard problems is itself a very hard problem and takes a lot of time, effort and practice. I've seen my share of "clever" solutions for hard problems and the problem with those is that usually the solution itself is so hard to understand that depending on the size of the problem it may take a developer from hours to days or even weeks to understand how that "clever" solution works. It's a rare occasion when a developer has come up with a simple solution to a hard pr...
Read more