Journaling for technologists

I encountered a question online recently about building context quickly, and whilst I thought of the bootstrapping post I made before, I also wanted to take a chance to explore how that plays into continuous practice. I started journaling as a researcher to remind me of all the dead ends and configurations I’d tried. Although I’ve not been entirely consistent in journalling (or sometimes blogging) each day and each new discovery, I think it’s a good practice for technologists to develop. Think out loud, even if it’s to yourself.

When building context on a new project, for example, I often find it useful, as part of discovery, to note what the client (or in very rare circumstances the written requirements) says it does, as well as what it actually does.

And always, always, journal everything. How to get it running locally, how to release, who knows what, who has the admin rights,… Anything that takes more than 2 minutes to figure out.

Sometimes that journal will take the form of shared content to help the next person join the project (and like all good scouts we should leave a place better than we found it), but the important bit is to write it for yourself. 80% of the time future you won’t need it, but that 20% makes the time absolutely worth it.

Advertisement

Managing across distances

As the government is starting to ease lockdown and put together timescales for allowing a return to the office, I thought it was worth revisiting some of the ideas I discussed in cross-country coding to see what applies to the upcoming hybrid world, where we know we’re capable of working remotely.

Obviously there will be done time to adjust as we inevitably feel with the mental health consequences of the anxiety of returning to the office as well as the adjustments we’ll need to add or undo to deal with family life, all the new pets and babies that have joined since the start of lockdown, and the mental space we’ve held for new hobbies, for home schooling, for the new health rules.

So take this as a waypoint on some future journey.

I’m not qualified to talk about the mental distress or whatever changes you need to accommodate in your life, but I want to think about how your employer and the technology may need to work in this brave new world.

• Face to face matters. If you’ve seen someone out breaks down barriers to talking to them. Video beats phone, in person beats video.
• Trusted insiders are very useful, when there’s multiple offices, or a team you need to check in with that you’re not in all the meetings for. There’s always small things that are missed when you’re just looking through the window.
• Invest in video. It needs to be good quality. Get better broadband. Get better webcams. Get better microphones.
• But try and be asynchronous. As soon as there’s friction to synchronous communication, collaboration plummets.
• Reminder that in open offices, people prefer electronic communication. “The impact of the ‘open’ workspace on human collaboration | Philosophical Transactions of the Royal Society B: Biological Sciences”
• Set expectations. Emergent behaviours only happen through observation and feedback, and distance dampens both dramatically

Blank spaces : how to deal with nothing in API design

Consider the following HTTP endpoint:

GET /{user}/appointments

How do we deal with nothing?

Nothingman

🚫 If the user doesn’t currently exist, return 404 – this informs the caller that nothing can be done with this resource until it is created or recreated.

🙈 If the user exists, but we want to protect against username enumeration, return 404 – this removes a route for malicious agents to identify actual users, perhaps prior to a password brute force. They may decide this endpoint is less likely to have the full protections afforded to the login endpoint. This endpoint should also avoid indirect enumeration, for example returning immediately for “user doesn’t exist” and delayed for “user exists but we’re pretending because security”

🔒 If the user exists but the caller doesn’t have permission to see their appointments, return 403 – caller will have to login, or ask someone who has access.

Empty time

Given the selected user exists

🔐 If this user does not support appointments, return 404 – these resources can’t be found.

🗓 If this user does support appointments, but there are none, return an empty list.

note : some APIs will return 204 No Content in this scenario. 204 should only be used for POST or PUT requests to indicate server action was a success, and there’s no data to send back

Empty space

Given the selected user exists
And they have at least 1 valid appointment (see business for what “valid” means)

📺 If the appointment has no location (because online conference links are saved elsewhere in the appointment body) then no location property should be returned

❔ If the appointment has no location (because it is unknown) then the location property should be returned with no data (the empty string)

Somebody else’s problem

Sometimes dividing tasks creates inefficiency. When one person both cooks and cleans, they tend to create less washing up than if the tasks are divided, because washing becomes “somebody else’s problem”. However, when one person washes and the other dries, the load is equivalent. This setup can be prone to stoppages when the drainer is empty and the washer is trying to get that stubborn burnt bit off the pan, at which point any good ToC practitioner will ask the drier-upper to help with the washing to maintain throughput.

When teams are divided by layer instead of features, the interface between them becomes a fracture because each team has context missing from the other. Data has the wrong shape, validation requires fields that can’t be captured. If you build both sides, the transition is smooth.

When developers test, they can focus on smaller, independent chunks, which means fewer tests with greater coverage. Writing integration tests for complex calculations is painful and slow. Testing those same calculations as an xUnit Theory is cleaner and faster.

Specialists are great, but where is specialisation causing fractures and more work?

How do you know when it’s time to move job?

Around 18 months ago, I decided I needed a new job. It took almost 8 months to find my current job, and I swayed between wanting to leave and wanting to stay. In the end I discovered that I was finding excuses to stay because I’d been there long enough, and made enough friends, to be scared of leaving. But the company I left was a very different company to the one I joined.

If you’re starting the new year after some time off, starting to fear going back, or having doubts about your job, have a think about these things, and see where you stand. Then decide if you want to stick or shift.

Some of these are things I’ve felt, others are ones that came up from multiple people in recruitment interviews I’ve done over the last few years.

• You don’t see yourself here in 5 years
• You have more direction than your company
• You’ve lost sight of, or respect for, the company values
• You do all your learning, and all your best work, out of the office
• The idea of doing the same thing next year fill you with dread. But it’s exactly what you expect
• You’re ready for the next step, but you can’t see where that step is.
• Your team, or your company, is shrinking, and no plans for growth are forthcoming.

What’s made you switch jobs?

How to mentor

​Once you start getting experience, you’ll find other developers asking for your help. I started tutoring at university so that I could help, and reflect and improve my own knowledge. 

Mentoring isn’t about answers. It’s about learning how to find the answer. The most interesting problems we deal with are the ones that no-one knows how to do. 

When someone asks for help, help them to help themselves. You need to start asking questions to help them find their own way. 

A successful mentor makes themselves obsolete quickly, but remains available to keep asking questions. A successful mentoring process leaves the learner with autonomy and support. 

My favourite quote from my tutoring days was a pair who, after I asked them enough questions to finish the tasks, said “I like you because you make me feel smart”. 

If you’re hiring the right people, they will be smart. Make sure the mentoring and onboarding reforces that. Smart, confident people are the ones who solve problems. 

CodeCraftConf take-aways

I’ll let the other guides at CodeCraftConf summarise their talks if they wish, but here’s a few quick takeaways that I want to record.

Simplicity

Simplicity is always good to strive for, but the most interesting question for me is how to tell when code is not simple enough.

It happens when we get frustrated, and swear, when we start to experience cognitive drag when trying to understand what it does.

Cloud

Nothing is secure (just ask anyone who’s filled out the PCI compliance questionnaire)

Lean coffee

Alignment is the most important thing to get out of meetings.

2 backlogs – how do we capture the idea that not everything on the backlog is equal? Maybe you need a “ready to start” definition as well as a “definition of done. Maybe you need a “we’ll definitely complete this sprint” vs “we’ll look at these next”, or maybe you just need to read Warren Buffet talking about focus.

 

CitizenM is a big improvement over last year in terms of noise levels.

Usable APIs follow-up

Following the Usable APIs guided conversation at CodeCraftConf, I wanted to capture some of the thoughts that came out.

Starting an API (as a user or a developer)

• Does the API documentation include examples of usage (i.e. have they thought about the client)
• How mature is the API?
• How well maintained is it?
• How long does it take to get to the first success (e.g. 200 OK – assuming success doesn’t mean error).
• What’s the versioning policy?
• What’s the contract?
• What’s the shape of the data?

Changing and retiring APIs

• Never, ever, ever, change the endpoint.
• Give as much notice as possible of changes (and never negative notice).
• Provide migration guides to clients, or automation scripts, such as the Python 2to3 migration scripts and guide.
• Be proactive – there was an example given of a web API (I can’t remember which one, sorry) that changed their endpoint, and created a bot that searched Github for usages of the old URL, and submitted pull requests for the new usage.
• Deprecate, then kill, once usage falls below a threshold.

Foolproof APIs

• Provide helpful errors, and treat unhelpful errors as a bug.
• Guide users into the pit of success.
• Follow existing conventions and standards.
• Be consistent.
• Document all the options and overloads.
• Postel’s Law : “Be liberal in what you accept, and conservative in what you send”.
  • But it’s very, very easy to get it wrong. Just look at IE6 and the broken web.

Isolation and proxies

• Log everything to detect unreliability.
• Make sure proxies are kept up to date with the underlying API, and fail gracefully when the API changes.
• Expect failure.
• Data is key – don’t give up more than you have to.
• Make sure, as a server writer you understand the client, and the network.

What is an agile developer?

@joe_jag a developer who practices continuous improvement, with our without the support of am agile team.

— craignicol (@craignicol) September 29, 2015

A developer who practices continuous improvement, with or without the support of an agile team.

You care about being better. You consider code to be craft. You’re only happy when you deliver value, so you want to deliver value more often. You set yourself a high bar, and always try to raise it. You want to learn. 

You accept your mistakes and move on. 

What does an agile developer mean to you? 

For those of you coming to CodeCraftConf, I’ll see you on Friday. 

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.