Reading: The Part of Writing Great Software

Posted 1 week, 4 days ago | Originally written on 12 Oct 2020
Writing great software is 99% reading documentation.

I've previously written about the stages of software development. They are the hack, refactor and integrate stages. The reason the first stack is called 'hack' is because it's usually a representation of a hurriedly put-together product - something you've hacked, as though you really don't know what you're doing. Your goal is to test a proof-of-concept, see that it works, in as sketchy a manner as possible. You don't want to waste time with details such as documentation, clean user interfaces and other irrelevancies (though you must integrate tests right from the beginning - more on that later). You want to receive the satisfaction of completion before you can now think things through properly.

But once you are done with hacking you want to go back to the drawing boad and begin the process of refactoring. Refactoring is the answer to the question "what is the simplest model that is underlying my current feature scope?". One of the best ways to answer this question effectively is to read. Widely.

To See Far You Need Strong Shoulders

There will always be craftspeople better than yourself. You will never write software 100% from scratch - there's no such thing (and even if there is it's probably a vanity project, anyway). However, in order to move fast - and you do need to move fast - you need great documentation. If I were to rate the usefulness of a software tool (language, API etc.) perhaps the most important factor is the documentation. Good documentation is a clear testament that the authors of the underlying software have spent considerable time thinking about the models. In our software stages lingo they have heavily refactored and integrated their code.

Personally, I find the Django documentation to be some of the best written documentation out there. It has a lot of things going for it.

  • It is written in prose. I can read prose.
  • It is well-structured. Over time I can predict (without relying on a search) where I will find a particular document.
  • It is varied, which appeals to different learners' ways of thinking. It consists of tutorials, how-tos, API documentations, and best practices.

I also find the official Python documentation extremely helpful. I typically dispense with free hours poring over modules that I have little familiarity with. For example, recently I've been heavily studying the section on concurrent structures and network and interprocess communication. Such binges leave me with an image of growing clarity on the true essense of computing.

Till Death Do Us Part

One graphic way in which I think about reading related to writing software is using a marriage metaphor. I like to think that you need to be married to the documenation. You should always have an open tab in your browser to the documentation. You should memorise links to your documentation by heart. (To the point that you learn that you can successfully open Python standard library pages without adding the '.html' extension - I bet you didn't know that! Did you also know that docs.python.org doesn't use cookies and it thus avoids the need to be GDPR compliant?) These documenation details need to be on your fingertips otherwise you'll succumb to the sullied alternative.

The Sullied Alternative

Be warned. Doing what I'm about to describe (and I know you do this - because I do it too) will shorten your lifespan as a writer of software. Trust me. I tried it once in a previous life and I got so burned out that I wanted to quit.

As mentioned, during the hack stage you don't really care how pretty the code looks like. You don't have time to read any documenation. You reach for a surefire way to get to the finishing line, with a promise to get back to things later and clean things up: you practice code-by-search-engine (CxSE, pronounced coxy).

Everyone does it. No-one knows the documenation at the beginning by heart. The main culprit, of course, is the poorly-written intro, which forces you to read for your seach engine and start CxSEing. Soon enough you are on stackoveflow.com (purveyors of hacks) and not long after your hack is up and running. Given the stress it's gotten you to get to the finishing line you depart for a distraction with a promise to clean things up later. But life happens. Babies are born, viruses spread and your routine is madly disrupted. You have other emergences to respond to - perhaps fixing some other hacked code because of a ever-expanding feature scope and never enough Q2 time for a refactor and integrate step. Eventually, your CxSEy code makes its way into production and the business is purring gently until some clever soul decides to deprecate something your hack depends on. At this point the gates of hell are swung wide open.

Do this constantly and you could cause serious trouble. It's called a hack for good reason: it's dirty and should never be deployed. Never.

The Flipside

It's one thing insisting that great software comes from tonnes of reading but the reverse applies just as much. Want to write great software? Don't be economical with words then. Software is only as good as its documentation. Write great documenation so that those who use your software will have every chance to do the same. In a word: read, code, repeat.