Translating Developer Talk cover image

Translating Developer Talk

Oliver Sarfas • June 18, 2019

career programming

API, REST, Integration, debugging, the list goes on. What are your developers on about? How come a simple button takes so long to make? There's something being lost in translation, and we're going to address it here.

Base Rules

From the start, there's a few basic rules of communicating with any member of staff, regardless of whether they're a developer or not;

Only you are paid to know your job, skill-set, and processes

There's nothing bad with being wrong. Accept it, own it, and move on.

Never assume

"It's not that simple"

Ok, situation time. You ask your developers to add a new button to your website. The button is going to do some arbiritrary action, let's say Sign Up To a Newsletter. Great, you go to the developers, give them a nudge and say "We need a button putting in our footers that signs up users to our newsletter. They need to give the email address - ok?"

Naturally, this seems a simple enough job right?

User submits email

Button pressed

"🎉 Congratulations, you now get newsletters! 🎉"

Job Done.

Well... not quite. There's a lot more that goes into that simple button than you're aware of, and that's why your developer said "Sure, but it's not that simple. It's going to take a few hours" instead of the "Sure, give me 5 minutes" that you were expecting. We have to guard against some situations, heres' a few I can think of immediately for this scenario;

User's email is already in the newsletter members listing

User submits an invalid email address

The Newsletter provider is offline

User submits someone else's email address - two-factor signup required!

GDPR - how are we logging all this?

What about the button in mobile, tablet, desktop - it's going to look different in each instance.

That list took me all of 1 minute to think up, so there's going to be more that could be added.

This is why the "add a button" job, is not simply 5 minutes. Theoretically, we can throw a button on a site in seconds - it's the "wiring" behind it that takes the time.

"It's not built for that, this is going to take a while"

This can mean one of two things, each with their own nuances.

Unexpected Feature

As developers, we like to preempt features that a client will request. So we'll build the main setup with that in mind.

An example of this would be an e-commerce site with some products. I'd suspect that the client will want discounts at some point, so I'll leave the pricing process open for extension, allowing for discounts / price hikes to be added in at a later stage.

Sometimes, we get this wrong. This is usually because the developer in question worked alone on a project or had little / no communcation with the project manager(s) stakeholders at the time.

As such, the software (under the hood) is skewed towards this "expected functionality", instead of being agnostics to it's uses. This can cause very tightly coupled restrictions in the code, which are hard to unwind and reconfigure.

Poor Architecture - "Hack it in mentality"

There's a principle in programming called SOLID. It's a set of guides that all programmers work towards. They are not rules, nor regulations, but a simple "do this, and generally things will be great" setup for us to work with.

One of these is the Open/Closed Priniciple (O). In a nutshell it means that our software, and the architecture behind it, should be open to extension but not modifiable in it's core.

As such we should be able to "easily" add new features to something, without altering the core functionality of the piece; as that's closed off.

"It's unstable / fragile"

This **does not **mean unstable as in it will crash everything and your company will burn. Nor does it mean unstable in a security sense.

Unstable in a developer's mind will often reflect how well something has been built / setup. It can mean one, or many, of the following;

Changes will have adverse effects elsewhere

There's few/no tests for this piece of code

As much as people love to believe, developers do take pride in their work and will always strive to build something right. However, due to various factors in any project, there is often cutbacks on resource and time; this leads to Spaghetti Code, and Technical Debt. Code which is ridden with Debt and Spaghetti infrastructe causes instability in the terms that a developer would express.

On the off chance that your solution is "likely to crash and burn", a developer would not refer to this as fragile. They'd most likely mention something to do with the Server Stability, or Uptime Issues. They may express is as "expected intermittent availability" as well.


Integrations is a term used for "making one system talk to another".

The most common integrations that you find in software are;

Payment solutions

Google's various solutions

Maps, search, distances, directions, Google Drive, etc.

Address lookups

Transactional Email providers

Used for better logging and structure to common SMTP solutions

Integrations are generally done through "Services", or using a 3rd party SDK (Software Development Kit). If your solution(s) built on modern technology, these integrations are fairly "bread and butter" nowadays, and can be built in a couple of days. Some of the very basic ones (such as for UK postcodes) can take a couple of hours.

API, REST, "Jason", SOAP?

Ok, so developers are lazy. REAL lazy. So we make up abbreviations for near enough everything we can. These 4 are a perfect example of this;

**API: Application Programming Interface - **Any form of exposed "interface" for a given application. The most common ones in Web are JSON APIs, and occasionaly you'll find a legacy SOAP API.

REST: Representational State Transfer - **A set of conditions that a web service must comply to inorder to be **RESTful. You will commonly find REST paired up with JSON. REST will let your developer know what to expect when interacting with a service.

"Jason": JSON. Javascript Object Notation. A lightweight, and easy-to-read format for data based on the JavaScipt programming language. JSON is very flexible in how it's used, and all modern solutions have methods to both handle it inbound, and methods of exposing it. It's the standard for web communications nowadays.

SOAP: Simple Object Access Protocol. This is JSON's older brother. Before the days of JSON, most web services were SOAP using XML instead. It was a very strict protocol on how web services interacted, and was defined in a WSDL file which you'd either download, or have exposed to your application. This is thankfully being phased out in most places, however you do find it in the wild sometimes. From my experience the financial sectors in the UK still use this a lot.

Questions? Want to talk? Here are all my social channels