Bad change : The rock star developer and dealing with unexpected change

Have you ever worked with a developer who knows everything? The one who does a bit of tinkering in the evenings and weekends, and when the rest of the team come in, they can’t find anything in the code?

Yes, it’s a bit neater, but it’s a lot more broken, because it’s less readable, because it’s using a beta version of a library rather than the previous stable version. And one project in the solution uses different conventions to the rest.

I also tend to find the tinkered code is proof of concept with minimal testing, and little documentation. So the software diva who developed to the limit of their ability can’t tell you how it works 1 week later. They got bored and moved on. After all, there’s another Javascript framework to learn.

It’s great if you write throwaway code. If no project lasts more than a month. But that’s not the software I’ve been building. I enjoy the challenge of nurturing code that’s got a lifespan of 5, 10, 25 years or more. Not necessarily the same code, modules get rewritten, tests get added, dead code is removed, but it has to remain readable and maintainable all the time.

If you are a lead with a diva on your team, use them for research, because they will chase The Precious whenever something shiny comes into view. But when they need to get code into production, enforce your coding standards strictly. They will moan. They will sometimes throw a tantrum. If they do, you know they’re wrong, otherwise they’d have a convincing argument for doing it their way.

Standards are universal. Divas are occasionally useful idiots. Learn to spot them, and use them to your advantage without disrupting the rest of the team.

Advertisement

Did you have a useful week?

Did you learn something? Did you stretch yourself? Did you challenge your assumptions, or your practices? 

Do you feel like you achieved something last week? Did the frustrations inspire you to make it easier next week? Did you share them with others, in the pub, or on your blog, so others can learn from your frustration? 

Did you set new goals? Are you going to be a faster typist? Are you going to learn functional programming? This time, are you going to lose weight? 

Did you make new connections? Did you make an effort to understand the people you work with? Did you do something to strengthen your work and personal relationships? 

You don’t have to do all of that. But did you think of it? Did you write it down? Did you, in some small and agile way, improve yourself? 

Can you say to yourself, today, that you had a useful week? 

Embracing Agile Architecture

Good architecture can respond to new requirements.  It’s malleable where it needs to be.

A good leader trusts their team. And builds their team so they can trust them.

Architecture leads software, it defines the agility of the rest of the development, and it defines the fixed points that cannot be changed, that will always tend back to the initial conditions.

Get the architecture right. Decide as a team, and document the decisions as you go. Sometimes a decision is made on a proposition that is false. Sometimes the best solution yesterday is no longer the best solution today.

Everyone should be designing architecture of the system, and everyone should be reviewing it (pull requests on the written decision are great for capturing the discussion).

Your job as a leader is to make sure those discussions happen and are productive. Put the architecture decisions and the associated documentation next to the code, so they are as open for extensions and available for refactoring.

Democratise the architecture – get everyone to buy in, and you won’t come back to the project in 5 years and wonder when the monsters and hurricanes attacked.

Event Horizon : When sharpening the code means missing bug zero.

A great programmer sees software as a craft, honing a perfect solution from a sea of binary logic. Good software is beautiful outside and in, and even on a large scale is simple enough that there are no obvious bugs. They produce software that is precise and clean down to the last detail, continually improving quality. 

But it’s easy to fall into the trap where quality beats everything. The software cannot ship until every bug is fixed, every scenario is covered, even the heat death of the universe. And the software still hasn’t left your machine.

Until your code is in front of your users it’s an untested hypothesis about what they want and what they can use. And hypotheses, no matter how precise, have a habit of not surviving contact with reality.

Test early, test often 

So start with a smaller hypothesis. Remember that for most of what we do, Newton’s laws of motion are good enough, and simple enough. Unless you’re building something that depends on very precise timings and/or very high speeds, you don’t need to handle relativity.

So ship it.

Build it. Test it. Ship it.

Prove your hypothesis meets the real world, and use it. Define your MVP. Cut it to the bone. And ship it.

Make sure you’re building the right thing: ship it.

Bug Zero 

Every project has a bug zero: no-one can use something that doesn’t exist, and isn’t live.

Fix that bug first, because every other bug depends on it. Either the bug is important enough for them to complain and tell you want they want. Or it’s never used, so remove the functionality.

 

Developers are Users Too : Why the User Experience of Your API sucks #yourapisucks

Many thanks to those of you who came along to my talk on why your API sucks. There were some great discussions during and after, and I hope I’ll be seeing slightly fewer reasons to tear my hair out in the near future.

A few things that people mentioned that I want to discuss again, as they’re not on the slides.

APIs still need a view model

There was a question about the API view of your data vs the database view. A good API still follows MVC principles. Just because a View is written in JSON instead of HTML doesn’t make it a model. Isolate it, because otherwise a database change is an API change. You can use automappers to save you having to write convertors, but always create a view for your API so you can handle versions and create consistency.

There was also a big discussion on how deep the hierarchy should be, particularly relating to data obesity. And it’s a different tradeoff if you’re optimising for poor latency, where larger packets with redundant informatio make more sense, or timeliness where small packets that can be built and parsed quickly are preferred. It all depends on your users. It may be the case, as the Trello API does, that returning the deep hierarchy is a request option so that the user can decide.

User Experience doesn’t always mean asking the user

Developers will ask for lots of things that aren’t useful. Sometimes you need to discover what the user needs are. Maybe it’s a test-first design. Maybe it’s a loosely typed API to help you discover what users want to do (think Google search vs Yahoo’s hierarchy – Google is more loosely types so was more likely to return odd results, but Google had lots of data on what people were searching for that it could learn from).

Link suggestions from the audience

Thanks for these suggestions. I’ll have to try them out myself, so I’m putting them here without warranty.

Kong – to consolidate your APIs, and create the polished surface that doesn’t expose the dirty, inconsistent history behind it.

RAML – to design a typed RESTful API up front so you know what it will look like.

Heroku’s HTTP API design guide

Slides from Google Docs

Slides from Slideshare

Your API sucks : how to suck less

If you don’t want to be chased by a horde of angry developers with axes, here’s a few things to keep in mind. And also see the making less-bad API tips from my DDDScotland follow-up post.

User first : Design from the outside in

Use Test-first design. And get developers to test it. Preferably developers outside your team. Developers understand *Unit, so you don’t need Cucumber, but make sure you have the tests.

If there’s a standard, use it

Use standards. Use libraries that support those standards.If the standards aren’t enough, extend them in the supported ways.

Be consistent

Your API is not a tree. You may be able to track the history of your source code by counting the rings, but the external façade should be smooth and polished.

Be clear

Make it as simple as possible, but no simpler.

Be helpful, but only when asked

Have documentation handy, and don’t be afraid to link to other documentation, even from 3rd parties. But don’t require documentation for the happy path.

Planning: the green and amber list

When doing scrum planning, trying to figure out what can be achieved in a sprint, there’s always variation. Especially in projects where you can’t rely on what came before. You can use yesterday’s weather, and break down tasks, but if you can’t estimate more accurately than “between a day and two weeks”, and you can’t use Kanban, and you have a big enough team, one factor I’ve found useful is to create two backlogs for the sprint. 

In the green list is all the things you know you can complete, and are the most important. The amber list is what you know you can start but can’t guarantee to finish. These might be bigger, exploratory, spiking tasks, or smaller, less important ones that can be done by the developer who finishes the spiking tasks towards the lower end of the estimates. 

Mostly these tasks are the highest priority for the following sprint and will move to the green list, but occasionally they will be smaller tasks that can roll over to the next amber list – such as a task you want a particular developer to handle as a quick win in a new area of code. Importantly, they are never blocked and always ready to start at any point in the sprint.

How do you deal with minimum and maximum caps for scope when planning? 

Your API sucks : testing

Finally, you’re ready to launch, you’ve integrated the API, you’ve decoded the documentation, you have passing integration tests, and FAT passed against their test server, with their test data. You go live. And everything breaks.

Strawman testing

Sometimes the test data or the API out of sync with live, and you find you’ve been testing the wrong thing. Maybe the test server is a version ahead of the live API (if they’ve ignored the advice not to version HTTP APIs).

More frustrating is when the data is plain wrong. When the returned record has { Firstname = “Lincoln”, Lastname = “Abraham” }, or an invalid postcode (did you know, The final two letters do not use the letters CIKMOV) which means the test site may require a postcode that your validator will reject.

Tests doomed to succeed

Sometimes the test data is correct, but incomplete. Imagine a postcode lookup where test addresses are all SW… which means you can’t test for:

• Flat x/y addresses
• BFPO addresses
• Irish or other EU addresses

Or imagine a payment processor test stub that always returns success – so you can’t test for declined cards, or 3DS cards, or check that you only accept debit cards.

If your API supports it, put it in your test, and make it available to users for their tests. If it’s not tested, it’s not complete.

 

Excellent Export, IE and Security

Following on from supporting large Client-side spreadsheets in Chrome, I’ve extended my pull request to also support IE, which uses its own proprietary Javascript method. Because, Microsoft.

And all was good with the world.

Until a Microsoft update broke HTML-formatted XLS files. Because, Microsoft. If you support XLS downloads on your site, and your users are getting a blank Excel window when they try and open them, thank Microsoft, and a security fix. Then go back to using CSV. Or ODS.

Thanks Microsoft.