Title: Speak Up!

Author: Martin Moene

Date: 08 November 2016 16:57:24 +00:00 or Tue, 08 November 2016 16:57:24 +00:00

Summary: Pete Goodliffe urges us to speak to the animals (that is, to other developers).

Body: 

The single biggest problem in communication is the illusion that it has taken place.
~ George Bernard Shaw

It’s the classic stereotype of a programmer: an antisocial geek who slaves alone, in a stuffy room with dimmed lights, hunched over a console tapping keys furiously. Never seeing the light of day. Never speaking to another person ‘in real life’.

But nothing could be further from the truth.

This job is all about communication. It’s no exaggeration to say we succeed or fail based on the quality of our communication.

This communication is more than the conversations that kick off at the water cooler. Although those are essential. It’s more than conversations in a coffee shop, over lunch, or in the pub. Although those are all also essential.

Our communication runs far deeper; it is multifaceted.

Code is communication

Software itself, the very act of writing code, is a form of communication.

This works several ways...

Talking to the machines

When we write code we are talking to the computer, via an interpreter. This may literally be an ‘interpreter’ for scripting languages that are interpreted at runtime. Or we communicate via a translator: a compiler or JIT. Few programmers these days converse in the CPU’s natural language: machine code.

Our code exists to give a literal list of instructions to the CPU.

Every so often, my wife leaves me a list of jobs to do. Make dinner, clean the living room, wash the car. If her instructions are illegible, or unclear, I won’t do what she actually wants me to. I’ll iron the cutlery and hoover the bathtub. (I’ve learnt to not argue, and do what I’m told, even if it makes no sense to me.) If she wants the right results, she has to leave me the right kind of instructions.

It is the same with our code.

Sloppy programmers are not explicit. The results of their code can be the equivalent of ironed cutlery.

Code is communication with the computer. It must be clear and unambiguous if your instructions are to be carried out as you intend.

We are not talking in the CPU’s mother tongue, so it’s always important to know what nuances of its language get lost in translation to our programming language. The convenience of using our preferred language comes at a cost.

Talking to the animals

Although your code forms an ongoing conversation with your mechanical friend, the computer, it does not just speak to a CPU.

It speaks to other humans, too – to the other people who share the code with you, and who have to read what you have written. It is read by the people you are collaborating with. It is read by the people who review your work. It is read by the maintenance programmer who picks up your code later on. It will be read by you when you come back in a few months to fix nasty bugs in your old handiwork.

Your code is communication to other humans. Including you. It must be clear and unambiguous if others are to maintain it.

This is important.

A high-calibre programmer strives to write code that clearly communicates its intent. The code should be transparent: exposing the algorithms, not obscuring the logic. It should enable others to modify it easily.

If code does not reveal itself, showing what it does, then it will be difficult to change. And the one thing we know about coding in the real world is the only constant is change. Uncommunicative code is a bottleneck and will impede your later development.

Good code is not terse to the point of unreadability. But neither is it lengthy and laboured. And it is most definitely not filled with comments. More comments do not make code better, they just make it longer – and probably worse as the comments can easily get out of sync with the code.

More comments do not necessarily make your code better. Communicative code does not need extra commentary to prop it up.

Good code is not trickily clever, deftly using ‘advanced’ language features to such aplomb that it will leave maintenance programmers scratching their heads. (Of course, the amount of head scratching does depend on the quality of the maintenance programmers; this kind of thing always depends on context.)

The quality of our expression in code is determined by the programming languages we choose to use, and in how we use them. Are you using a language that allows you to naturally express the concepts you are modelling?

We must talk the same language at the same time, or we’ll suffer a biblical Tower of Babel cacophony. The team working on a section of code must write in the same language; it’s not a winning formula to add lines of Basic to a Python script. If your entire application is written in C++, then the first person to add code in another language had better have a compelling reason.

However, even in an environment using the same programming language, it is possible to use different dialects and end up introducing communication barriers. You may adopt different formatting conventions, or employ different coding idioms (e.g., using ‘modern’ C++ versus ‘C++ as a better C’).

Of course, using multiple programming languages is not evil. Larger projects may legitimately be composed of code in more than one language. This is a standard for big distributed systems where the backend runs on a server in one language, with remote clients implemented in other, often more dynamic, browser-hosted languages. This kind of architecture allows you to employ the right kind of language for each task. We see here yet another language in play: the language that those parts communicate through (perhaps a REST API with JSON data formatting).

Consider also the natural language you program in. Most teams are based in the same country, so this is not a concern. However, I often work on multi-country projects with many non-native English speakers. We made a conscious choice to write all code in English: all variable names, comments, class or function names, everything. This affords us a degree of sanity.

I’ve worked on multi-site projects that didn’t do this, and it’s a real problem having to run code comments through Google Translate to work out if they’re important or not. I’ve been left wondering whether a variable name has a Hungarian wart at the start, is misspelled, abbreviated, or if I just have a very bad grasp of the natural language used.

How well code communicates depends on the programming language, idioms employed, and the underlying natural language. All these have to be understood by the readership.

Remember that code is read by humans far more often than it is written. Therefore, it should be optimised for reading, not for writing. Use a concise construct only if it’s easier for someone else to understand, rather than easier for you to type. Follow a layout convention that reveals intent clearly, not one that requires fewer keystrokes.

Talking to tools

Our code communicates even further – to other tools that work with it. Here ‘tools’ is not a euphemism for your colleagues.

Your code may be fed into documentation generators, source control systems, bug tracking software, and code analysers. Even the editors we use can have a bearing (what character set encoding is your editor using?).

It isn’t unusual to add extra directives to our code to sate these processors’ whinging, or to adapt our code to suit those tools (adjusting formatting, comment style, or coding idioms).

How does this affect the readability of the code?

Next time

So: code is communication. It’s the kind of communication we continually strive to improve on.

In the next instalment we’ll step beyond this, and look at how to improve our interpersonal communication. We’ll consider how we communicate with other people, with the wider development team, and even – shock horror – with the customer.

Questions

• How clear is the code you write?
• Does it always communicate your intent?
• What can a programmer do to improve communicate when using code as a medium?
• Should the code you write be adjusted based on the audience you expect for it (e.g. the make up of the team that are working on it)?

Notes: 

More fields may be available via dynamicdata ..