Ddd.scot, diversity, and your career

I had a great day at DDD Scotland, thanks to everyone who came along for the discussions. Apart from the panel sessions I chaired and participated in, Joe Wright ran a great mob programming session, Gary Fleming led a lean coffee session, and we had a couple of great lightning talks about recruitment at Skyscanner and Becoming a Technical Lead From Tugberk Ugurlu of Redgrave.

There were a few recurring themes that I want to highlight.

Diversity

This was a strong recurrent theme throughout the sessions in the community room. Whilst the focus was on gender due mostly to the makeup of the attendees, a few people pointed out the need to respect diversity for LGBT, age (graduates don’t have 5 years experience), family circumstances (single parents and others don’t have time in the evenings to do coding interviews), dyslexia and autism. To which I’d also add physical disabilities, skin colour, religion, any of which can and have been used intentionally or otherwise to limit the pool of candidates brought to interview, or created a hostile environment once in the job.

If you want to hire on merit, don’t just give the job to the white guy because he’s “a culture fit” and recognise that your recruitment may be biased. When I put an ad on Stackoverflow, all the replies were men, but working with a couple of recruiters we found a better mix of candidates, including the woman who we ended up hiring.

No problem at all, great to hear that people are keen to learn about it! The link for the next WiTS event is here. It would be great to see more of you there! https://t.co/BJvYmdNmbO #DDDScotland

— Becca Liddle 🏴󠁧󠁢󠁳󠁣󠁴󠁿 (@The_Liddler) February 10, 2018

Job hunting and moving on in your career

There was a scary graph that suggests that computer scientists are less employable that other graduates, and yet of all the STEM subjects, there are more vacancies in software (where the stem jobs are ).

Computer Science graduates can't get jobs, but employers are desperately looking for developers. What's causing the gap?

Trying to find answers at @dddscot #dddScotland pic.twitter.com/W498p0DNgy

— craignicol (@craignicol) February 10, 2018

The job market is broken. There’s a lot of smart people out there, and for my last 2 jobs I had no experience in one of the key technologies they were advertising for, so the job adverts in many ways are meaningless. I want to work with people who have the skills to evaluate the next JavaScript framework, not 10 years experience in Vue. Nothing I work on today existed when I graduated. No ASP.NET MVC, no REST, JavaScript was for image rollovers, no Swift, no Xamarin. But job adverts don’t care about ability to learn. They’re a checklist.

I know recruitment agents get a bad reputation, and for some it’s well deserved, but a good one will help you get past the keyword gate, because they can sell you on your potential. If a company isn’t interested in your potential, choose another one. If you don’t want to deal with an agent, you need to be bold, demonstrate what you can for the requirements, and find examples to help them see that you can learn the rest quickly.

But have examples. You don’t want to be the clueless braggard who can’t even FizzBuzz.

Culture of learning, and mentorship

If you want to continue to be successful, you need to learn. Some of it you can do on your own, some you’ll need help with. If you’re working for the right company, they’ll provide you with a mentor, but even if they do, it’s worth finding others to help, whether it’s a formal process, or just someone to discuss if all companies make you deal with that stressful thing that’s getting you down.

Write a blog, volunteer for projects outside your comfort zone that help you improve those skills you’re lacking. Seek feedback. Accept that you won’t know everything and the learning experience is littered with failures. Learn by doing. Pair, mob, spike ideas.

When you’re tired of learning, find a new job.

Advertisement

Ddd.scot panel sessions and lightening talks

I’ve been selected for 2 sessions at DDD Scotland this year. There’s no presentation from me, but I’ll be chairing a panel, and appearing on another, so plenty of opportunities to answer questions. This is a new thing for ddd.scot, as well as the lightening talks stream to help you practice public speaking, or just share something cool. Please come along and provide your feedback.

If you’re coming, please submit a question to the Your Career in Software Development panel so we can answer the questions you have on your career. Submit your question anonymously here

Hope to see you there.

Your API sucks : foolish inconsistency

There are many ways that an API can be inconsistent. Different methods can follow different conventions, one method may have different results, or maybe a change introduces inconsistency between versions.

Spatial Inconsistency

When calling 2 different methods in what appear to be related domains require 2 very different calls and get 2 very different results.

GET /cat

{ Name : “Garfield” }

GET /food/index.php/fooditem/1

                    🍌

Random Inconsistency

When calling the same method multiple times can lead to a result with a significantly different format.

GET /cat

{ Name : “Garfield” }

GET /cat

{ Name : “Jatt” }

GET /cat

{ Name : “Lion-o” }

GET /cat

🍌

Temporal Inconsistency

When versioning an API breaks existing clients without warning. Speak to Seb Lambla if you want to do it without versioning, or Troy Hunt if you want to version it right, in all the wrong ways.

Today:

http://www.example.com/api/getAddress?postcode=EH28%208PL

Tomorrow:

HTTP POST
 http://www.example.com/api/getAddress
 X-www-form-urlencoded
  API-version: “v1.1”
  Search-type: “postcode-lookup”
  Input: “EH28 8PL”

Your API sucks : Error handling

Exceptional validation

So many places I’ve seen throw an exception for the first validation error they encounter:

HTTP 500 - Credit Card number invalid

When I see that, I need to make multiple calls before I can see what’s wrong. If you’re going to validate, try and validate everything beyond authentication in one shot, like this:

HTTP 400

{
    validationErrors: [
        {"CreditCardNumber" : "Must be 16 characters"}
        {"ExpiryDate" : "Must be in the future"}
        {"CCV" : "Is required"}
    ]
}

Success : ERROR

If something went wrong, make it obvious. On the web, use a 4xx or 5xx status code, instead of a 200 OK. In code, throw an exception. This isn’t C, we don’t need to rely on errno any more. If I see success, I want valid data. Parsing your error messages isn’t part of the deal. Especially if they have spelling mistakes.

Illegal characters

If I see that your API won’t let me have O’Malley as a name, or Flat 1/2 as an address, I will immediately start thinking of Bobby Tables, and I will assume you have a poor encoding excuse at your backend. If you can’t handle that, you shouldn’t be writing an API. As the security sucks said, you should not be my weakest link.

Your API sucks : hidden effects

Your API can be well structured and use the right language on the surface, but it can still be a pig if you get it wrong behind the scenes.

Data bloat

Are you sending 1/2 Gb of data for every roundtrip? XML encoding the entire object graph for a call that can only possibly change 1 field within it? Are you wondering why your network is slow?

Busy waiting

Sometimes data is big. It will take a long time to upload and process. That doesn’t have to be a problem. But don’t make me wait whilst you do it. It’s easy to find asynchronous libraries, or just throw the request in a queue and return. Let the client get on with the next thing.

Idempotence

Idempotence is a posh word for a very simple idea : looking at something shouldn’t change it. Quantum mechanics is hard because that’s not true. Your API is not there to impress Niels Bohr.

In other words, GET over HTTP doesn’t change data. Property getters on a class don’t change data. CQRS queries don’t change data. Don’t change data unless explicitly requested to do so.

Don’t get confused though. This doesn’t mean that each get will return the same result, after all tomorrow’s weather will be different to today, but I should be able to change the weather just by observing it.

Hidden prerequisites

Have you ever visited a shopping site and tried to checkout, only to be denied because you haven’t previously added a credit card to your account?

It’s very annoying having a hidden step that’s not clear. If it’s required, make it required at the point of action (definitely my preferred option), or if you can’t do that, deny access to the point of action until the prerequisites are cleared. And make it very clear why access is denied.

Your API sucks : security

Pop quiz time.

You are given the following example URL to GET as an example of making a payment from your application. How many things here would make you back away slowly before setting the server farm on fire?

http://www.example.com/api/pay?cardnumber=1234123412341234&ccv=1234&expirymonth=12&expiryyear=12&amountinpence=123456

So you complain it’s unsecured and they come back with an upgrade, so you need to make the following call first:

http://www.example.com/api/pay?username=bob&password=supersecret

If you’re sensible, you will walk away. A API should never be the weakest link in your code. Remember, you own everything, including the turtles all the way down. Users don’t care that it was Honest Joe’s Honest Payment Provider that had a security hole, it was your site that took their details, so it’s you they will blame.

Your API sucks : Domain languages

You have a massive data set. You have geolocation data for the entire country. You are the king of GIS. And to prove it, you’ve developed a postcode lookup so people can check your database.

Your clients write their code and format their postcodes, and, like every other system they use, they expect that submitting a postcode will return an address. You’re the GIS expert, and you say the result should return Easting and Northing, because that’s what your database uses, and your database is right.

The clients look at the result, realise that your API returns garbage because it’s not using the language they expect, and move on to another provider.

Congratulations, less users to support.

Your API sucks : DDDScot follow-up

I was disappointed to miss DDD Scotland this this year, as I was looking forward to catching up with everyone and giving my talk. I’ll have to do the catching up another time, but if anyone wants me to give the talk, I’m available for conferences, user groups, weddings christenings…

There’s still a few discussion points I want to have around the talk, so I’m going to be posting some themes from the talk over the next few weeks to see what you think.

I wrote the talk as a catharsis for a project with 3 very bad APIs.  I don’t want to name them in the talk because none of them were the first time I’d seen the problem, and I’m trying to list general anti-patterns so that other developers can avoid the pitfalls. The key one being that for all the user experience research, most people still think of users and interfaces as graphical, not programmatic.

Before I start the rants though, I want to start with 2 thoughts about making an api that sucks less.

Test-first

The best way to think of the user first, is to be the user first. That’s why I like Test-Driven Design. Write the API you want to use, then figure out all the horrible contortions behind the scenes to make it happen. That way you’re far less likely to introduce unexpected preconditions, because they’re harder to test. You’re far less likely to expose internal domain terms and models  so long as you’re not thinking about them yet. And you get to experience any frustrations first hand when you’re best placed to fix them.

Use BDD, use xUnit, use Postman, use the wonderful new .Net core

TestServer.GetClient()

. Keep using them. Don’t accept any pain in your interface tests.

Rest, and be thankful

The talk unashamedly focuses on Web technology, and REST, for all the trial warfare, is a great way to think about the interface, and some of the basic lessons apply to other interfaces too:

• Be open for extension – where you can, build extension points into the interface. Use dynamic models if you can, allow discoverable interaction (I’ve got my order, what can I _do_ with it?)
• Use the standard – if you’re building on top of http, use headers, content-type, appropriate verbs, because existing clients and test frameworks support them, developers have learned how they work from other interfaces. Don’t be the stone in their shoe.
• Minimise state transfer – don’t ask clients to remember, don’t ask clients to send or receive large amounts of data. Scope requests to the smallest sensible unit, and only ask for what you need.

Anti-patterns

Sometimes it will go wrong, and you will make developers cry. I’ll start talking about those next time but feel free to add your own below.

DDD Scotland: your API sucks

I’ve had a talk accepted for DDD Scotland, so many thanks to those who voted for me. I’ve got a few tales of APIs (particularly, but not exclusively Web based) that made my life as a developer harder that it should have been. Whether it’s Security, bad versioning, incoherent naming, or JavaScript’s Date object (zero indexed months? Seriously?), there’s a lot of bad decisions made in interfaces for other developers.

I suspect that a few of you have stories of woe with APIs to work with, and I’d be interested to hear any you may wish to share, to make sure that the suggestions I’m presenting are universal, and not just pain points that I’ve had.

So, now’s your chance to get cathartic over those libraries, Web services, OSes and other APIs that have ruined your day. What API makes you wish you’d chosen a career as a baker?

PS remember that developers are your users, and they want your data, or your service, not your API. Strive to make developers forget your interface.

DDD Scotland Voting last chance

Voting for DDD Scotland is open until , I have 4 talks and an open discussion session submitted, but there’s lots of other potential speakers and talks. Looks like a fantastic lineup for the comeback conference, so go vote, and thank the organisers for getting it back.

See you there.

PS. Apologies for the short post, it’s been a crazy busy week for me – I’ll have some more details later, if you missed my tweet.