Programming Practices – Should Programmers Take Writing Lessons to Enhance Code Expressiveness?

code-qualitycoding-styleprogramming practices

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.

Best Answer

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.

Related Topic