Comprehensible languages x Expressive code x The other side of the world

One reason to care about expressiveness

Most developers agree nowadays that mantaining software is an important task, either refactoring it as a task is completed or one year later when new functionalities are added, the cost of maintainability should be kept as low as possible in most cases.

Mentioning most cases, i automatically exclude pieces of code or complete software written by any group who intentionally write in such a way that no common programmer is capable of understanding. I wrote this article only for those situations where the way you express your intentions becomes important in order to others – or even yourself – to understand it.

Lack of communication: a geek’s problem

Expressing ourselves was never the best of our abilities. As a stereotypical geek, I am a shy person whould only be able to freely express my intentions after a couple of beers. Being an uncommon practice to communicate with other type of people (not so much logical-driven thinking), does not give a geek a lot of knowledge on how to express his ideas in a more sensitive and human way.

Being also a hard task on its own to develop code without abusing from logical structures and tricks, everything contributes to make it a very difficult job for developers to write comprehensible code.

So why does your code looks comprehensible right now, but anytime later, completely uncomprehensible? And you just start to hate what you did? After refactoring it becomes, again, more comprehensible?

Its quite uncommon for one to get ideas quite clear in one’s head, prior to putting it on paper. How many times have we had those really bright ideas, and as soon as we write them down, the idea does not seem so clear? As we talk about it with other people, and come back to the same piece of paper, we can make our ideas more clear. It does not happen only with ideas being written on paper.

Artists face the same problem while painting, they do not know exactly what to paint, and may come back again and again in order to improve something they thought were ok, but later realized that was still not what they wanted to communicate through their art. The same thing happens with writers too, a book or an essay is not simply written. It is proof-read, re-writen, until the text passes to the reader the original idea that the writer wanted to pass.

Even great communicators may not achieve their best result on passing on their message on their first attempt. Why would a developer, sometimes a geek with dificulties to express himself as a person, would be able to express his idea in a great way at all?

So far, we have a few ideas on why is that expressing our ideas is important (maintaining software) and why is it hard for us developers to express our ideas (cultural issues, lack of practice, continuous improvement required).

Being born in a family of teachers and educators, I learned back home how important it was the ability to forget our current knowledge and talk to someone (express ourselves) as if the other end-point has no knowledge at all. This is the most important quality of a teacher… being able to level himself in such a way that his knowledge is exactly the same – nothing more – than his students.

Mindnote: it was not enough to lose my shyness, only enough to allow me (maybe) help some other people.

Being able to think in advance that our readers do not have the same knowledge that we do helps us to write (anything, not just code) text that can be easier understand by them. That is just a hint on the mindset one may have while writing.

Enough about communication skills, let me talk about what has been my passion for the past 2 years.

Koreans and japaneses

I still ask myself how do koreans and japeneses feel when they get a first glance at western grammar. Both languages share the same structure which is based on the “subject objects verb” sequence, in a completely different fashion of our’s commons “subject verb objects”. Furthermore, they share the notion of descriptive verbs and korean (I do not know any japanese) has suffixes to identify those objects in a much similar way that most languages uses prepositions or (german/latin) declinations.

We can illustrate the basic difference with a single sentence, when I would say “I went home late”, koreans would “I late home went”: “저는 늦게 집으로 갔어요”. Easy right?

Lets pick a daily life example with two phrases: “because i had no money with me, i went to the bank”. In korean? “with me money i had none because i to the bank went”. This single order change makes it really hard for us westerns to learn korean. But what about imperative sentences?

“you 1st room from 5th room until big room breakfast with rent!”

Maybe even for non-linguistics developers/fans, it might be easy to understand meaning hidden in the above paragraph. But might this change of order help us write better code? Should we start asking koreans and japaneses? Will it make it possible for me to write code which people will understand easier?

In the following paragraphs I will show what my mind went through to find out that:

• I do not know the answer because korean is not my native language
• It might be too late for korean developers to answer this question as they are already used to the way of thinking the programming languages oblied them to think
• there is room for programming langauge improvement to allow us writing more expressive/easier to understand code

By the way, for those (if any) who did not understand, I gave an order to rent a big room checking in on the 1st and leaving on the 5th with breakfast inclusive.

Symbols x Language

Due to the obvious nature of this post, I am making no comments on languages as perl and haskell which appeals to (too many) symbols as a way to express one’s intention. Symbols are really great for defining abstract ideas. Symbols are hard to teach, to learn and to understand. And if someone makes just a small change to the set of symbols understood, your life becomes hell. Those languages go completely against what I – as a teacher/educator – think this is the right way of communicating one’s intention – in our case, express our code.

Symbols might achieve more results with less effort, but at the same time symbols are harder to understand. I will be glad to change my mind the day someone teaches a common person how to code in one of those languages faster than teaching someone how to code in ruby.

Our aim is not to create complex software or in cases where developing faster is not the only issue in game but keeping the code understandable is a issue, “too-much-symbols-based” languages do not offer what other languages do.

Coding, “korean style”?

This section will describe the problems I have faced while trying to do something similar to the way korean grammar expresses its sentences.

Because most languages were written with a western language mindset, they all only offer one way of declaring parameters, which describes them after what we recognize as the action being invoked. For example, in most languages, the rent order would be defined and invoked as:

invocation:
bigroom.rent (from: 1st, to: 5th, for: me, with: breakfast)

definition:
rent date from date to client for boolean with

I have chosen some type-definition-required-based language so the definition looks a little bit more natural to human eyes (yes, rent from to for with would be lesser compreensive).

But what if I wanted to use a language that values objects over actions. If you think about parameters as the objects, the object in which methods are invoked as the subject and methods/functions as verbs (this supposition might not always apply), one can see that our commonly used languages do value actions over objects. Actions define which objects they receive, instead of parameters defining which actions can be taken.

One simple change would be to write the invocation in a koren style:

invocation:
bigroom 1st부터 5th까지 ... rent

Soon, one starts to notice that 부터 (from), 까지 (until), 에서 (at) etc is not actually the variable type definition but something else! It is not the name of the variable itself, it is something else! What? Let’s come back to it really soon… but first,

What would be if things were completely written the other way around? In a way that parameters itreact with themselves and define the actions that can be executed with them? I have absolutely no idea how to define actions, given parameters, therefore I just left this question open and tried to think about other ways to improve what I write.

Language garbage

Note that if I define being garbage anything else that I would not require to express my idea to another human being, the above example if just full of it. Let’s remove some of the clutter:

invocation
bigroom rent from 1st  to 5th for me with breakfast
definition:
rent from checkin to checkout for client with optionalBreakfast

First of all, both sentences are much more natural, although the invocation could be written in a more imperative way as “rent the bigrrom from 1st to 5th for me with breakfast”, let me keep my exposition within OO based-languages.

We can also notice that I have removed type definition and added something else… that is still unclear what it is. And this is exactly what I think that we might try out. That is what I pointed out in the previous section.

Programming languages which do not allow us to invoke methods by using the parameter’s names are much less expressive than the ones which allow us (i.e. ruby):

invocation not using parameter names:
bigroom.rent(Date(1,7,2009),Date(5,7,2009), guilherme, true)

What??? What is the first, the second, the third and the fourth parameters? It is quite clear that the above piece of code lacks something in order to communicate what it really does. It lacks the parameter names (lets call them the parameter ID’s now, ok?).

But how do Java developers write expressive code without using named parameters? Easy, just extract variables!

invocation with “named” args:

from = Date(1,5,2009)
until = Date(5,7,2009)
client = guilherme
withBreakfast = true
bigroom.rent(from, until, client, withBreakfast)


Extracting variables was the refactor chosen in order to solve the problem or language limitation did not allow us to do it: use identifiers to our parameters. Now let’s see another example with a language which would accept parameter ids:

invocation in a language which uses named parameters:

bigroom.rent(from=Date(1,7,2009), until = Date(1,7,2009), client=guilherme, withBreakfast=true)


Its clear the same solution as with the Java language, but written in only one line. The disadvantage is that the line gets longer – and therefore more complicated. The advantage is that a language which obliges parameter ids to be passed forces our code to be more expressive and comprehensible. Unfortunately ruby does not (yet?) forces uses to write this way.

Note also that forcing parameter ids, one removes the need for creating tiny objects for developing small dsl apis. But this approach would not be recommended in a api which should be easily extended because tiny objects (used through their interfaces) are easier to extend.

Lets go further? The korean way of writing sentences showed me something that even the english approach does misses. Forcing parameter id’s was the first move and improves the ability to write invocations that are easier to comprehend. But what about the function/method definition? Can we improve something there?

current invocation:bigroom.rent(from=Date(1,7,2009), until = Date(1,7,2009), client=guilherme, withBreakfast=true)

current definition
rent from checkin to checkout for client with optionalBreakfast

But look, first of all the definition includes no parameter type definition, but does include the parameter id and something else. What is that something else?

If i rent, I have a checkin date, and the checkin date is identified with the from id. Therefore each parameter has actually “two unique identifiers”. An internal one which is used within the action/function/method definition, and an external one to be used when invoking the method. Our code would be implemented somehow as:

define rent from checkin to checkout for client with optionalBreakfast as

bookings add new Rent from checkin to checkout for client with optionalBreakfast

end definition

The above implementation invokes the Rent construction definition and invokes the add method in the bookings list.

Mindnote: symbols for adding items to lists and so on are, again, symbols, therefore not the most comprehensible feature of mankind.

Is it clear? Clear enough? Clearer than some other approaches? I can see it as a better way of writing codes but unfortunately I do not know any language so far that can help me this way. Let me try it a little bit further with a conditional statement:

if amUnavailable from checkin to checkout
then complain about unavailability
otherwise bookings add new Rent ...

Do I need to explain what is written here? Well, now ask your grand mother if she understands the above protocol. And yes, do not call it “logic” or “code”, call it a protocol… non-programmers would get it easier if you call it a procedure or protocol instead of “logic” or “code”… just a matter of names but allows people to better understand what you are saying.

Some languages would require the type definition, I understand those languages have reasons for thinking this is the best approach (yes, i am still a Java programmer and prefer defining variable types) and this could still be implemented in a more compreensible way using the above mentioned approach.

REST, URIs and experiments

Should URI’s express what they represent? What about the limitation on the Http methods when I am using web sites for human (not machine-to-machine) iteraction? That is what has been keep my mind busy yesterday, and will probably stick to mind while on the plane to Korea… it is just a pity I do not have access to Korean children so I could get their feedback on computer programming before they get a grisp of english.

Comprehensible languages

Summing up, I believe the code would be much more expressive and comprehensible if the language we use force us to use parameters with ids and IDEs helped us by given those names and not allowing us to change them. Simple changes, that would perhaps help others understand what we wanted to say.

Comprehensible languages would be programming languages which allow us as human beings to express ourselves in a way that we can understand each other instead of through abstract logical symbols.

Anyone willing to implement such language?

So what does Korea has to do with all this? Well, I always prefer telling people the history on how I come up with any idea.