This is the second post in my series: Coding Without the Jargon, where I show how I clean up and gradually improve real-world code.
Rule #2: write your code so a smart 12-year old with no programming experience can follow the general idea.
You’ll be so glad when you need to revisit that code in a few years time.
Advanced Language Constructs
CPU cycles are cheap, human attention span is expensive. In my book, trading CPU cycles for code that is easier to read and understand is a good trade.
Many languages and frameworks provide clever ways to express complicated concepts in just a few characters. If you live and breathe that environment, you can express a complex operation with very little code. That gives you a short-term ‘win’.
Now picture the situation where someone who is not as familiar with the advanced language constructs needs to understand and maybe adjust the code.
That someone might be someone new on the team.
Or it might be you, six months or a year later. By now, you’ve switched to a new framework, and you might have forgotten the more intricate details of the previous framework. Frameworks and language features come into and go out of fashion at a rapid pace.
Or I might be showing my code to someone who knows how to code, but does not know ‘my’ language.
Or maybe I am on holiday and the project manager, who does not speak the language fluently wants to try and check on how some process works.
It is to my benefit if they still can ‘grok’ the gist of what the code does, rather than get mired into weird and wonderful constructs.
The way I tackle this is to try and avoid advanced language or framework constructs if I can.
If the benefit of the construct is mostly in conciseness of expression, rather than an extreme performance increase, I’ll avoid using it.
If I do use something fancy, I will document it clearly in the README so future-me doesn’t have to reverse-engineer it.
Code Like A Graphics Designer
Just like in graphic design and publishing, white space is a crucial tool for guiding the reader’s eye. Code readability can be increased tremendously with thoughtful use of empty space.
When laying out a flyer or article, designers don’t cram every inch with content; they use spacing to make structure visually intuitive.
I apply the same principle in my code: I use newlines, indentation, and vertical layout to reveal the structure of complex expressions.
It’s not about saving lines, it’s about making logic visible.
Small Steps
When coding I see my code as a whole sequence of ‘thoughts’.
I have no formal definition of what a ‘thought’ is but as I read through code, my brain will step through these thoughts.
If the thoughts in the sequence are simple, the code is easy to follow.
If a thought forces the reader to mentally solve a Rubik’s Cube, the code is too complex.
I try to spread out thoughts and make sure there is room to ‘breathe’. The mind of the reader needs to digest what it has seen and get ready for the next bit.
By breaking up the code into small ‘thoughts’ and introduce them gradually, rather than ‘clump’ it all up in a dense pile of clever code, I try to make the meaning clear.
I only worry about performance after all is said and done: premature optimization is the root of much evil. When writing code, I will not worry about performance – I only worry about making the code readable. After all, in my experience, choosing the right algorithms is much more effective for getting good performance than writing dense, high-functioning code.
I will often introduce ‘one-time-use’ functions to make thoughts clearer, by putting a name to them.
For example, grabbing a file name extension from a file name or path can easily be written out explicitly, but even so, I’ll still wrap such expression into a function, say getFileNameExtension(theFilePath) or so and make it easier to grok the code.
Sometimes I work with the concept of ‘stories’: I don’t adhere to the idea that functions should always be short or have a proscribed maximum length.
Some of my functions might span multiple pages. These I see as ‘story functions’ – they tell a story, and artificially breaking them up might disrupt the story and makes them hard to follow. Stories tend to go like ‘this and then that, and then that, and then that…’, i.e. a nearly straight sequence of calls into other functions.
My code will be mostly short functions (one thought per function), and might also have a few long functions (one story per function).
Next
If you’re interested in automating part of a Creative Cloud-based workflow, please reach out to [email protected] . We create custom scripts, plugins and plug-ins, large and small, to speed up and take the dread out of repetitive tasks.
If you find this post to be helpful, make sure to give me a positive reaction on LinkedIn! I don’t use any other social media platforms. My LinkedIn account is here:
