… something on Code as Content
Code is no longer buried away on a knackered old pc acting as a server long after its useful life should have been over. It is now kept and browsed on the Internet, even if with restricted permissions, reviewed, commented on, argued over and discussed but all too often needs deciphering to be understood.
What do we need to think about to support these use cases better? How can we be kinder to our users, our future selves, and our colleagues?
I’m just starting to explore what makes it easier for view, review and comment on code, to improve its quality and also the communication between your team and teams.
Web-based Code
With the wide adoption, almost ubiquitous, of git, a distributed version control system (VCS), and in particular services like Github, Gitlab, Bitbucket etc, code is now probably more widely viewed through a web-browser than an IDE (Integrated Development Environment) eg Visual Studio, IntelliJ, Rider, VS-Code.
That is to say, with modern development practices, for each person editing the code, the rest of the team often views any changes as part of a code review or Pull Request (PR), list of changes on a branch, etc.
This is especially true for Open Source projects, where the whole world is able to view code.
It is not just around the time of commit, someone may just casually browse the code at any time, or be searching for when a particular commit was made.
As has been long said code is written once, but read many times. This is becoming increasingly true.
In the beginning…
Subversion (SVN), which some of us used in prehistory, did provide a way to view code through a browser, but just as plain text, and lacking many of the navigational niceties we have today.
Generally though, code used to be something buried away, with only the chosen ones allowed to view it — even if you had a Need to Know, you didn’t necessarily get to see it, now it is accepted that anyone can have a browse.
With this dramatic shift in consumption of code, it seems sensible to start considering the Code (Re)viewer, who often you are relying on as a second pair-of-eyes to agree to your changes, as a third distinct audience for your code after you and your compiler. And don’t forget, your future self will become part of that third audience, when all memory of the current change (be honest, should I say hack?) has faded.
So what can you do?
So firstly, and lastly, think about your audience.
Which is just as likely to be your future self as anyone else.
And my Gold Standard of Awfulness is this: what will I say if I’m having to deal with this at 3am, needing to get something out the door as urgently as possible?
Keep your lines short so you don’t need to Scroll…
Many developers now have multiple wide screens as standard, giving them 200 characters, even 300, to play with on a single line.
If you’re not careful you end up with lines so long they end in a different timezone.
However, if you ever had to work on a laptop you wouldn’t have that many and would have to scroll back and forth to read the whole line.
Browsing the code online gives you 100–120 characters at most.
Even worse if you go to the side-by-side difference viewer where each version of the file gets only half the page, there are only 60–80 characters available on each line before you end up in scroll-bar hell.
And, No, zooming in or out of the page doesn’t help.
It turns out the human eye is far better at reading shorter lines, which provide more structure, and why one writing this now on Medium my text is only filling the middle third of my screen. Because it is easier to read like that.
Resist Indentation Inflation
Firstly, think on the following quote, which puts it far better than I ever could:
“The answer to that is that if you need more than 3 levels of indentation, you’re screwed anyway, and should fix your program.”
https://www.kernel.org/doc/Documentation/process/coding-style.rst
A second terror lies in the arbitrary indentation schemes used in many places. There also tends to be indentation inflation, as Kevlin Henney describes, in his “Seven Habits of Ineffective Programmers” talk (do watch it!) much of it makes no sense.
Only increase the indentation gradually, don’t suddenly increase an indent to line up with the end of a method name above — it becomes arbitrary, and you end up hitting the right-hand side of the page earlier than you need.
This also means that the visual guide of any indentation you do have keeps integrity, and (for example) a parameter list stays on a contiguous area of the screen.
Is this not easier on the eye?
Allow the code to breathe
Finally, the denser the text the harder it is to read. This starts to get more subjective, but allow some space around the code.
Group related lines together — even within a method — but, for example, when you have created on object you need, allow an empty line before you create the other one you need. Think sentences and paragraphs.
Why have I started a new line here.
Yes, it comes down to quite well understood typography and its principles.
Conclusions
Too much time and energy is wasted on whitespace and braces Holy-Wars. Formatting too often gets prescriptive. Indeed, you shouldn’t really be manually formatting anyway, but using an automated tool setup correctly which does it consistently.
But there are some important principles that you can use to make it easier for your future self as well as your team.
Keep each line short, keep indentation down, keep it consistent to allow visual cues. And keep away from horizontal scrollbars.
