… something on Code as Content

TheCodeCleaner
Nov 1 · 5 min read

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.

Code in an IDE

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.

Code Online

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.

Scrolling required

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.

Arbitrary Indentation

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.

What’s going on with here?

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.

Parameter list in two places, visually

Is this not easier on the eye?

The original example. How I’d laid it out.

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.

With a little bit of white, er, black-space

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.

TheCodeCleaner

Written by

@TheCodeCleaner agile consultant, committed clean coder, slayer of complexity and harbinger of tea. Remourner. Now 'part of the team' at @RedGateProdDev

Ingeniously Simple

How Redgate build ingeniously simple products, from inception to delivery.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade