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: Readability

Readability, understandability, two key incredients of great code. Easier said than done, right? What one person finds easy to read and understand another one finds incomprehensible. This is especially true when programmers have different levels of understanding on various subjects e.g. object oriented vs. functional or Node.js vs. Java. Even though there are obvious differences between paradigms and programming ecosystems there are some common conventions and ways to lower the barrier. Different approaches It's natural that in programming things happen sequentally e.g. you can have a list of objects and you need to do various things to the list like filter some values out and count a sum of the remaining objects based on some property. With the given list const stories = [   {name: "authentication", points: 43},   {name: "profile page", points: 11},   {name: "shopping cart", points: 24},   {name: "shopping history", points: 15},   {name: &qu
Read more

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: 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