Should a programmer take writing lessons to enhance code expressiveness?

Question

Given that programmers are authors and write code to express abstract thoughts and concepts, and good code should be read by other programmers without difficulties and misunderstandings, should a programmer take writing lessons to write better code?

Abstracting concepts and real world problems/entities is an important part of writing good code, and a good mastery of the language used for coding should allow the programmer to express his thoughts more easily, or in a better way. Besides, when trying to write or rewrite some code to make it better, much time can be spent in deciding the names for functions, variables or data structures.

I think this could also help to avoid writing code with more than one meaning, often cause of misunderstanding between different programmers. Code should always express clearly its function unambiguously.

Answer 1

1. Writing lessons? Not really.

Writing source code is different enough from writing a book.

While both pursue the same goals: being as unambiguous as possible and being easy to understand, they are doing it in a very different manner, and things a writer should learn are not the same as things a software developer should learn.

Example 1: figures of speech

Figures of speech are valuable when writing novels, poetry, etc., since they increase the expressiveness of the writing.

What is the last time you've seen an oxymoron or a litotes in source code? Would it help to have them, or would it rather be extremely harmful for any developer who will have to maintain such source code later?

Example 2: vocabulary

Rich vocabulary is highly appreciated in literature. Vocabulary of William Shakespeare, for example, is twenty thousand to twenty-five thousand words. Richer vocabulary makes it more interesting to read a novel or a poem.

When you write source code, you expect it to be read by people who don't speak English very well. Showing how well you know English would be extremely harmful for your code. If you know a fancy word which means exactly what you need but you know that lots of people don't know the meaning of this word, you should rather find a less expressive synonym or a set of words which explain the meaning. A vocabulary of a few thousands of words is often largely enough for a given project.

Note an important aspect: while Google Translate could be of a great help for a non-native speaker, there are two issues with any translator:

• A pair of languages don't necessarily have a 1:1 match between the words. Some words have either no translation in other languages whatsoever, or multiple words could translate into a single word in a foreign language. For instance, in Russian, there is a huge amount of words which target specific states of snow and cold weather, and translating them in French or Spanish is usually impossible without losing their specificity.

• A word sometimes has multiple meanings, and the meaning is deduced from the context. Google Translate, despite its high quality, is usually unable to indicate the meaning for any but the most basic situations.

Example 3: expressions

Expressions make prose richer as well. An author expects a reader to have a given amount of general culture, and uses this opportunity to make the text more expressive.

Similarly to the previous example, such expressions could be very problematic when read by people who are not native speakers. But if general vocabulary can usually be translated, expressions are much more problematic.

For instance, English is not my first language, and on daily basis, I encounter expressions, including here on StackExchange, that I don't know. I try to guess their meaning, and sometimes I'm right. But sometimes I'm wrong, and Googling those expressions doesn't help.

A user in her/his comment reminded me of an example which made me suffer for a long time when I just started programming: PHP's needle and haystack. I was unaware of the corresponding figure of speech, so every time when I was reading the documentation, I was wondering what is this all about. Needless to say that C#'s sequence.Contains(element) or the excellent Python's element in sequence are a much better alternative. Well, at least, developers who don't know Hebrew had to suffer from PHP too, but this is a different story.

Example 4: cultural references

Cultural references. In literature, it is tempting to include elements from a given culture, and this too makes the book richer and sometimes more interesting to read.

However, code is addressed to developers from all around the world. Therefore, what is an obvious reference for an Italian developer may not be that obvious for a Russian one, and what every Indian boy or girl knows may not necessarily be known by an American programmer.

The same user who talked about the needle and the haystack gave an excellent example of such cultural reference too: the Grail. Who doesn't know what Grail is? Well, I mean, it's “Graal” in French, “Grial” in Spanish and... “Kutsal Kâse” in Turkish, but still. However, how much American or European developers know the medieval history of China or India? Why would anyone assume that every Chinese and Indian programmer has to know the Holy Grail reference?

2. Lessons to write expressive source code? Sure.

• Any developer should learn how to write expressive source code.

• Any developer should explain why the comment in:

  int j = i + 1; // Creating i and adding 1 to it.
  

  is bad, even aside the fact that it's totally wrong.

• Any developer should be able to understand the basic refactoring and how it helps making the source code more expressive.

• Any developer should remember that 20% of the time is spent developing code, and 80% of the time maintaining it. For some projects, it's more like 5% - 95%.

• etc.

---

In essence, programming is close to technical documentation. Does a person who writes a spec sheet for a bolt need to take writing lessons? Not really. The same applies for developers. Anyone should write without making spelling mistakes in every word, and anyone should be able to communicate her ideas clearly enough. Aside that, I'm not sure how writing lessons would be more useful than, let's say, a course in Computer science or in IT security or whatsoever.

The expressiveness of the source code can be learnt by other means. superM mentioned one of them in his answer: reading good code. I can mention a few others:

• Reading books like Beautiful Code or Code Complete,

• Asking for a more experienced developer to review your code,

• Understanding patterns and how and when to use them.

Answer 2

should a programmer take writing lessons to write better code?

No. A programmer should take writing lessons to learn to write better prose. A programmer should take programming lessons to learn to write better code. Despite some similarities, writing prose and writing code are quite different.

That's not to say that programmers shouldn't take writing classes. They should! Some reasons:

• Writing is an essential skill for any educated person. You'll seem smarter if you can write well.

• Despite their best efforts, programmers frequently need to communicate with other humans, often using the written word.

• You learn skills beyond writing in writing classes, and those are often useful to programmers. For example, you'll learn to discuss other people's work without hurting their feelings, and you'll learn to accept criticism from others without taking it personally.

Answer 3

My code increasingly depends on creating a shared vocabulary between the business and the technical teams. I'd say that improving your writing skills can help you reduce ambiguity and misunderstandings in these efforts, but that it's not likely to help the expressiveness of your code.

The literary notion of expressiveness is not the same as the programming notion of expressiveness. In many cases, ambiguity in language can be used as a literary device, even in non-fiction, in a form that increases expressiveness, because it will trigger various cultural, linguistic and symbolic associations in the reader, both intended and unintended. This kind of expressiveness is not desirable in programming; abstraction is more valuable than ambiguity. In programming, abstraction increases flexibility with perhaps some cost of cognitive load. Abstraction in literary form can have the opposite of the effect it has in programming: the more abstract your writing, the more likely the reader will have the perception that you are saying nothing. All those symbols and associations that result from concrete speech have value, because they resonate with your readers more directly than abstractions.

However, a programmer is not a machine. Humans benefit in often unexpected ways from intellectual and emotional growth. Improving your writing may result in greater customer empathy because you force yourself to struggle with communication challenges; perhaps you'll feel for that customer who says what they want, then you deliver it and they realize it's not what they need. Perhaps you'll just learn to focus on what's left unsaid.

Maybe learning to throw clay on a pottery wheel will help you start to see parallels between craftsmanship and software development. Studying the way building architects communicate might lead you to have a stronger appreciation for building a vocabulary of design patterns in programming. Studying biology might lead you to fascinating insights about how ants and bees find and communicate about food sources and how those simple mechanisms could be translated into pathfinding algorithms.

Learning things outside of your core domain are worthwhile because curious people make better developers than people who aren't.

For what it's worth, I was nearly a literature major; I ended up switching to East Asian Studies because I was more interested in the classes I was taking in that department. There's a chance I might not be in the industry had I not studied East Asian Studies, because the side effect of studying Japanese made me more valuable at the time, when a software company hired me in part due to language skills. I still had to build a deeper portfolio of technical skills, but the unintended side effects of learning anything can make you a better, more relevant software professional.

Answer 4

When programming projects fail it's usually due to failed communication, generally around requirements. Though a mediocre grasp of English may be sufficient to actually write code, being a good communicator is essential for writing the right code. In this age of remote-working, text-based communication, English writing is a very important communication skill.

That said, your question is written in a very clear and concise manner - better than most programmers I have worked with. Not having seen your code, I'd suggest you concentrate on expressing yourself in the coding language of your choice. For Java, I recommend Joshua Bloch's book, "Effective Java."

Answer 5

Like writers are taught by reading world's classicals, so the programmers are educated by reading good code. But there is one little problem. While there are recognized giants in literature, there are few of them in programming. And if there are, they might "speak" a different language. (I'm not even sure that its reasonable to advise reading the Minix source code by Tanenbaum)

There are many popular ways to make code more readable (=> maintainable), like writing comments, giving meaningful names, etc. Besides, many companies establish their rules of writing code, and it makes everything much easier.

Anyway, like many excellent writers, programmers are never happy with their own code. So knowing when to stop is as important as writing quality code.

Answer 6

I always find simply stopping after each bit of code you write and reading it again, imagining that you've never seen it before, gets me a long way with this.

Even better is to ask a friend who is familiar with programming to read your code without telling them what it does.

Answer 7

I don't think that will help; creative writing is about plots and character development and dialog, not about expressing technical concepts with clarity. Technical writing might help, but I doubt it - they're just very different kinds of writing!

and note that "readable" code is subjective, and primarily a matter of syntactic style and common idioms (which vary among languages and even among teams)

choosing good names for variables and classes and methods, however, is important. Every developer becomes, to some degree, a subject-matter expert in certain aspects of the domain under development, so correct usage of domain terminology is critical.

peer reviews can help you build vocabulary and confidence

Answer 8

There is certainly a big difference between writing code and writing prose.

In prose the sentences are connected (or separated) by time (the way they follow each other in order to reach an end or meaning) but in (efficient) code you can (re)load parts of the 'story' from tables with repeatable actions/responses. So, the interaction with the reader (in prose) or user (of code) is totally different.

In another way writing 'nice' prose and writing 'nice' code are similar: learning to write (code or prose) is a process which involves a lot of making mistakes (or thinking/testing about improvements, or reformulating) to get it 'elegant'.

I think the chemical periodical system of elements is elegant, because of the very compact way it describes some fundamental properties of basic materials we use, a bit like efficient code but it is certainly not prose. A joke has a lot of prose qualities (getting you into a certain mood, keeping that mood and then change it, when unexpected) but that's an awfull coding practice.

But both types of writing ask for craftsmanship.

Answer 9

basic English and grammar is sufficient for a programmer from my point of view. But then any thing to break a monotonous programming routine will always be rejuvenating and so the writing lessons will be relaxing for the programmers.