« Brutal Refactoring | Main | Beyond 'Conway's Law' »

March 30, 2011



I tend to like my programming language to be quite readable by us humans - but I agree we shouldn't spend lots and lots of time forcing the Programming Language into English.

One place where I feel that a bit of that work IS worth it is in tests. To me the tests need to communicate with humans first and the computer second.

In non-test code the program needs to communicate with both the computer and humans at more equal level so compromise on language is fine by me.

Michael Feathers

@Verdammelt I'm inclined to agree... except, I think tables work well for tests too. It seems situational. I also wonder whether with tests we're seeing the remnant of the "tests should be readable by the end-user" mode of thought also. To me, it's "sometimes yes, sometimes no."


But I think tables are very readable by humans as well!

Michael Feathers

Okay, that's fair. :) I thought you were pushing the natural language thing.


Yeah, my point, was that tests need to be much more human readable - so i think working harder to make them readable is ok. For non-test code it is important to be readable - but more compromise on human vs. computer readability is fine there.


Readability can be associated with natural language but I (personally) think that's a bad association. I've always being wondering how a Chinese code looks like. How do they name variables and methods? If they do that in their language I prefer readability to be far from natural language. We can speak both the programming language, so it's better to use that. I've read programs that looks like Chinese, and I think that's the point of readability, the program should be legible.

On the other hand, people that don't know the programming language shouldn't judge readability, maybe they cannot read the program because they have limited knowledge about the language in which was expressed. This occurred to me when someone told me not to use the null coalescing operator (C#) because the resulting code was not legible.

I have seen also some coding that are written focusing in natural language and knowing the programming language doesn't help much to understand what's going on behind those methods, what is the result of the method when()?

This just to say that readability is not the direct result from using the natural language and (we all know this) is not achieved using just the programming language. Writing readable code is an skill, and as such, practice is required, a lot.



I think that line of code actually could be read as a narrative, if only you didn't have to write regular expressions.

If someone wrote an "object model" for git, wouldn't the code look a lot less intimidating?

`git log #{@filename}| grep ^commit`.split(/\n/).map(&:split).map {|fields| fields[SHA1_COLUMN] }

In Clojure, a syntax I'm a little more familiar, I could envision something like this:

(map :sha1-column (:commits (. git (log filename))

With pipeline syntax, we can arrange the words in another order that's a little different, but in general, it reads out:

"For each of the commits for a particular file, select its sha1- column"

I was a Smalltalk programmer before too, and I'm pretty sure the Smalltalk code can be made to look very close to the English I have above ;-)


I can appreciate where you are going with this, but I think that the visual form made me want to see if there wasn't a more expressive (less piped with less temporary elements) form and I came up with this:

`git log #{@filename}`.scan(/commit (.*)/).flatten

Except for the superfluous Array#flatten which is an artifact of how captures are treated within String#scan, I think this meets both structural and narrative criteria.

That is not to say that there isn't a place for both forms of expression, but I think that it's possible to find a good expression that transcends both forms.

Matthew Rodatus

The narrative aspect should not obscure the "structure that reveals computation," but I find value in using all aspects of the [computer] language to communicate to my future self and other programmers.

In chapter 23 ("See No Evil") of SQL Antipatterns, Bill Karwin talks about a related concept: writing readable code at the cost of leaving absent or obscuring important logic.

The concept applies to all languages -- not just SQL. A quote from the chapter: "Some computer scientists have estimated that up to 50 percent of the lines of code in a robust application are devoted to handling error cases."

Error logic is often ugly.

I agree that the communication with programmers should not supersede the communication with computers.

Mike Busch

Not that it's the point of this article, but getting a list of just the SHA doesn't require any ruby at all.

git log --format="%h" --no-abbrev

if you don't need/want the whole sha, you can omit the --no-abbrev flag.

Mohan Arun

I usually feel TDD (test driven development) is more of the 'visual' cognitive modality that you talk about related to neuro-linguistic programming. The visual stimulus for developing code is the stimulus of seeing tests perform.

John Rusk

Apparently experienced chess players "see" the board differently from beginners. I suspect the same is true from code - and that there are non-narrative ways of "seeing" that develop with experience.
There's an excellent recent book from Daniel Kahneman which goes into a lot of detail on this stuff. I posted a quick (and _very_ incomplete) overview here: http://www.agilekiwi.com/peopleskills/understanding-ourselves/becoming-an-expert/

Tom Ordonez

I got the feeling that some people want to build programs like in Star Trek. Talk to the computer in human English.

Some people mention to make it more readable. Readable to who? To programmers or to non-programmers? Unless you are trying to achieve Star Trek technology why would you want the code to be more readable to "end users". They don't want to read this stuff.

More readable to folks that have limited knowledge about the language? Why make it so easy for them. There is a saying in Colombia, "darles las cosas masticadas" which means give somebody the food already chewed. When you say this about somebody it means more like "you have to feed that person like a baby and hold their hand".

I believe in more readable to programmers (and technologists) with the goal of making the program more efficient. Not necessarily through words. Maybe the future is visual. We develop code through visual shapes where a circle may be a class, a square a function and lines to map between different objects. Maybe the future is auditory. Program through the use of sounds. The synthesizer is the sound of the future, according to Giorgio.


The easier you make it to understand code the easier it is to produce code. The easier it is to produce code the harder the problems you can tackle.

Code that matches how people think is easier to understand without a steep learning curve.

Yes, experts see code differently from non-experts just as when in mathematician mode I see math differently from most people. But matching language structure to how people think helps you go further faster. Generally elegance and brevity go together. If either are missing it is time to step back and think.

The comments to this entry are closed.