Writing clear code

There was a fascinating talk at this year’s Gophercon by Julia Ferraioli (and her Twitter account) called “Writing Accessible Go” where she covers how you can approach writing code taking disabilities in mind.

What is fascinating is that like the UI equivalent is that it also improves things for people without disabilities. It event references the drop kerb effect which I remember being brought up when I first encountered accessibility speaking to people at Mozilla. The simple improvements actually benefits everybody.

Although this is Go focused they are simple rules that can be applied to any language to make your code more maintainable, easier to learn, and look nicer.

You can view her slides here and the Gophercon page here.

Also there is a link to a talk about Python Code Style For Blind Programmers.

How to start fixing a legacy system

You join a new team and discover that what you have inherited is a bundle of bugs all holding themselves together, which presents itself to the end-user as a fully working system.

What do you do? Unfortunately I’ve been in this situation more times than I care to remember, so there is a way forward.

Normally when you join a team with a problematic codebase they try and say “What would you like to work on?” as in a project which is away from the central core. My answer to the question is “Give me bugs, I’ll learn the system that way”. It is unglamorous, but what you will learn is the way that people use the system, and also all of the problems in taking a small code change and checking it works and getting it into production. It is not just about understanding the source code, but understanding exactly what the current process with all its idiosyncracies. Once you have more of this context in your head you can then start to make a plan for how to improve it.

You will find that the steps are pretty standard.

  • Set up continuous integration. The spectrum will be from having none, all the way through to having a working pipeline that is just not running everything. Start with every commit to master then go on to getting pull request builds working.
  • Continuous integration should build the artifact that is required to run the product. You might also provide a deploy step as well.
  • Get the current tests running or get a framework ready to run. You’ll probably find there are some tests in the system but because they are not automatically run they don’t work. First get them working then add them as a stage in continuous integration. If there are no tests set up a test framework with a single dummy test and get that running to put a mark down of how to write tests.
  • Start running code quality. Add this to continuous integration on every run. Initially you will find you have to slacken off the checking and get it passing under less strict conditions as things like code formatting are less important than actual errors. Gradually over time you can then tighten up the rules.
  • The most important thing I find is if you can’t run your codebase locally you really can’t make any changes safely and have no way of starting to break things down for testing. In order to achieve this you may end up with multiple docker containers with each data dependency and a bunch of processes running. You’ll need to extract your database fixtures, and a myriad of other data, but ultimately ou will end up knowing the actual extent of your system.
  • Prune your code. Use the delete key liberally, less code is easier to manage. You’ll be amazed when you pull on some threads and the entire thing unravels and you end up with a huge percentage of the code gone.

To get to this stage you are probably looking at 1 to 3 months work depending on how bad and how complex it is. Each step allows you to get more sure about the process (and the order will depend on what is easiest to deliver).

Then you also have to actually make code changes, this is the whole point of this work. When adding a feature or fixing a bug make sure you add tests to that stage you did earlier, this may not be easy, so you have to have a few layers of testing to accomplish this.

  • Running locally. If you can run your system locally you can manually perform the steps to check it works. This is obviously slow an inefficient, but you are also in a position you can attach debuggers and inspect how the code is actually working.
  • Integration testing. This is the next layer, automate the steps you did manually when running it locally. This means you still require all the extra data dependencies like databases, but you can replicate the behaviour a lot more consistently than by hand.
  • Unit tests. Web frameworks have unit testing framework, and there are many available. As you understand the integration tests better you can work out how to mock out the data dependencies and run basically the same tests without requiring all the data dependencies. This makes them faster and more dependable, and also easier to automate.
  • Pure unit tests. When you have pushed through all those layers you can even take that legacy code and write reasonable pure unit tests where functionality at a low-level can be tested in the way they show you in books.

Developers tend to have various beliefs about which are most effective, but having all these options available gives you a path to take what is hard to manage code that nobody really understands to easily testable code which is easy to add to. Really, the best way to approach it is to be continually improving the code quality of your tests and trying to move them to a more stable, reproducible state.

Remember when the code is simpler and easier to read and understand, you can actually work out what the next evolutions for the codebase are and how to architect your way there.

This is a fairly short overview of some of the steps I typically take when starting on a legacy system that needs some TLC. It is not a quick fix but a long grind to get to a better, more stable place.

I Suck At Working Remotely

After over 15 years of working for tech companies entirely from offices I found myself in a new role where I needed to work remotely, be on-call, and not only that work with people on US timezones.

My initial concern was “How will I motivate myself to get started in the morning and keep it going?”, but this pales into insignificance as I discover the problem is “How do I switch it off?”

My boundaries were constructed by the divide of home and the office. This division meant that I had to leave at the end of the day and have a buffer (commuting by car or bicycle) for my evening. Working in the same place as I live has knocked that down. Bizarrely with my commute removed from my day I feel like I am spending even less time with my family than I was previously. I prefer to be an early morning type of person and have always been, this really is tricky when working with multiple timezones.

Now is the time I need to ask what other people do to cope, and the changes I need to bring in to go from what is an unhealthy work ethic into a more balanced life. I know a lot of people my age getting into deep anxiety (all lovely people who I would never imagine going down that route, but the human brain is wonderfully complex).

One of the weird things about working in an office is that you spend all your time with a small group of people in our company. When you have a family as well you spend all your time with your work friends or your family and you kind of forget you don’t have a proper social life outside of those two circles. I’ve also found that I don’t leave the village I live in that often now as there is little need to, but then you can see they deficiencies that were covered up.

As of last week I’ve decided that I am going to start addressing these problems piece by piece.

  • Every lunchtime go to the shops to buy it (can be expensive, but a mechanism to force me to leave the house).
  • Eating far more healthily and a no snack rule for me (I know I can consume almost unlimited calories). This is phase 2 of this particular plan and makes the first point less expensive.
  • Just stand up and go out for a bike ride mid afternoon for 30 minutes before PST timezone wakes up.
  • Start addressing the on-call anxiety which can cause me to freeze up and be far less productive. There are personal and technical items to address here.
  • Reaching out to friends and family again after essentially digging myself into a very deep hole.
  • With my children I have to make sure I’m unavailable for a certain period of time every evening for bedtimes and baths. Most of the time I have not failed at this.

And further forward looking because it is going to be difficult to do all changes in one go.

  • Start enforcing a “no evening work” rule and start actually unplugging at a more suitable time to have family and personal time. I know I am going to struggle massively with this, with products like Slack becoming more the norm they are massively intrusive.
  • I know I have to do some evening calls purely due to the timezone, but I should limit it to not all evenings.
  • Try to head into the London office more regularly, if for no other reason than to have more human contact.
  • Start to find a way to get to talks in Cambridge/London again by addressing workload.
  • Actually try a bit harder on the social life front.
  • Social media can be positive and a huge negative. It needs to be controlled more, I think reading books/comics distracts me from it more, but TV does not.
  • Start writing again. Just blogging to start with, but longer form than social media posts.
  • Look at co-working spaces for at least one day a week out of the house and village.
  • Or even find like-minded people who want to share an office space, not necessarily every day either.

I want to hear from other people who maybe have been through a similar process, or need to go through it. Advice, help and support always gratefully received (and given).