Some weeks ago I read a tweet or two about the relationship between coding and writing. One of them advocated that you’d become a better developer if you could write well, in the sense you’d be able to communicate better with people around you. You’d argue better, inquire better, and so on, which I totally agree with! It’s somewhat an obvious and spread idea, but few people use to really invest the time needed.

The other one pointed to the fact that, when you write code, you don’t write to communicate with the computer, but with the programmers that will maintain that code later (including you), which is also true, but not entirely. I believe we actually write to both of them, and that’s one of the things that makes programming difficult.

But even though both ideas are true, they are still superficial concerning the relationship between coding and writing, in my opinion.

I actually think coding IS writing, and not in a metaphorical way. But in real and concrete terms. And that identity holds in many different levels, not only in the most basic one, that coding is typing text, or that we conform to a language or anything.

I mean coding is writing in every aspect of it!

When we code a small module, looking for an elegant way of describing a specific algorithm we’re just like the writer that’s looking for the best wording to put an idea in a bunch of paragraphs.

And when we’re thinking about the whole architecture of your system, drawing boundaries, and defining macro components, we’re doing the editor’s work of negotiating with the author which chapter should come first, and how ideas should be presented.

We’re always trying to tell a story.

In programming, it just happens to usually be pretty big and complex stories, written in a very systematic and rational style. And that happens because the story we’re trying to tell is, most of the time, a precise and detailed description of a complex and boring system. We may be describing, for example, how a company does its business - how it welcomes clients; how they present products or services to them; how they charge them; how to interact with a partner to process payments, etc.

It’s such a boring story that needs to be written in the most practical and useful way possible. We’re not interested in how beautiful or pleasant your code is. We just want it to be correct, clear, and understandable by other people (including you) that will maintain it.

(You may argue that style matters a lot and that we sometimes should add a dose of art to our code. Or even that some people code art. All this is not only true but also corroborates the point I’m trying to make.)

I’ve always felt sympathy for the use of words like Story and Epic to describe a system’s requirements. They insinuate a similar understanding, that we’re writing a story. But I think they don’t capture the best from the metaphor with only those two levels. Maybe we chose the wrong scale. Maybe more appropriate ones could be to call a use case (a user story) as a chapter, and each scenario as a chapter’s section. Our epics could relate to a book part (a collection of chapters), and I’m pretty sure we could extrapolate that to volumes and even to a whole library making reference to a company’s portfolio. You name it.

I also remember how exceited I was the first time I heard, in 2008, David Chemlinsky talking about BDD, RSpec and Cucumber. I felt something very fundamental was behind allowing us to express our tests in terms of Subjects and Predicates; using structured language that would connect requirements and code through a semi-structured language. That didn’t get much traction, but I still think there’s something big in uncovering the connections between writing and programming.

Coding is a peculiar form of writing, not only because we need to write to two publics at the same time (the machine and the other developers), but also because we write stories while they are happening. Stories that change, like a moving target!

It’s also peculiar in that it needs to be extremely detailed in how the smallest things work and, at the same time describe the whole business of the company. Try to think about Amazon’s “library”, for instance. 😳

And even more: we’re writing a big and very detailed story about something that’s changing, to two quite different publics, AAAAAAND… (even as an implication of that), we need to write that collectively! Sometimes collaborating with tens or hundreds of other, often unknown, developers.

It’s definitely a hard story to tell!

But it’s still a story! And just like conventional writing, you need to be good at finding the best words (think identifiers in a code), the best sentences (think about functions), the best way to approach the story - how to break it, what to present first, what next (think about breaking and naming modules) and so on.

And writing is by itself a difficult thing! And, let me say that - at least in Brazil, programmers are often the kids that were good at math and exact sciences in school, many of which gave little importance to learning to write well. Consequently (at least in Brazil) programmers often write very badly.

That is the main reason why I think it’s such an important matter. How can people want to be good programmers if they are not good writers? I’m serious: go study writing! Go write a little. READ MORE!

Read technical literature, if that’s what you like, but try reading other things, also! And read it attentively with the way the stories are told. What do you like and what do you dislike about the author’s style? about the structure of the book? About the discourse tone?

Also, reading technical literature uses to be selective and consultative - just going to the section you need to understand a specific topic. And that is extremely effective most of the time. But when was the last time you read a programming book from beginning to end? It’s a completely different experience! You get acquainted with the author’s preferences and stories… You also read at a different pace, hearing the author’s prosody, making pauses. It’s very different! And so little practiced by most programmers I know.

In summary, in my opinion, to cross the boundaries between being a good programmer and being a great programmer, you really need to focus on the writing/authoring side of programming. You also benefit from it in many other aspects, such as communicating better with people that are writing the book with you (which is obviously a valuable thing!), but, most of all, if you write better, you’ll code better. Much better!