Fog Creek Software
Discussion Board




English Code

I happened across Eric Gunnerson's blog on "Why static import is bad..."  (sidenote: blogs.msdn.com is a great diversion when you're resting your eyes -- I've read a lot of interesting design compromise articles, as well as about technologies I otherwise would have ignored).

http://weblogs.asp.net/ericgu/archive/2004/06/30/169861.aspx

Interesting enough posting. One reader comment, by Darren Oakey, caught my eye:

`my test of readability =
"how long would it take someone who spoke english, but has never seen a computer in their life, to understand the code"  '

Ignoring the rest of Mr. Oakey's comment, and his perception that the world is one of exteme contrasts with clear rights and wrongs, I find his opinion on code readability interesting. It hits a sore point with me given that this sort of "race to the bottom' mentality dictates a lot of the ridiculously contrived "code standards" out there, and it undermines the profession (I once had to deal with a manager who would rate code based upon how easily he, untrained in the language, could understand it).

Should code aspire to being readable by any untrained dummy, or should it seek to be readable by someone reasonably versed in the particular language and technology? Should I seek to make my C++ easily readable by a HTML web slinger, or should I program with the artifacts and benefits of C++ and appropriately have the expectation that said HTML slinger will perhaps learn C++ to a credible level before complaining about the readability of my code? I won't even get started on Perl...  English is clearly more readable than German, as I can read English right now, but German would require me to go and learn a new language first.

Bah.

.
Thursday, July 08, 2004

"(I once had to deal with a manager who would rate code based upon how easily he, untrained in the language, could understand it)"

I can see why this would irritate you (or any other trained coder), but for the life of me I can't see this as a bad thing, given a certain minimal familiarity on the part of the reader with the basic syntax of the language.

Code readability isn't about operators, it's about comments, formatting, variable/function names, nesting, and flow of control.  Good code *should* be readable by the (relatively) untrained, if they have the patience to actually read it.  That's not to say that they'll grasp the subtleties, but your manager has surely been around enough code that he can get a general sense of it.

Justin Johnson
Thursday, July 08, 2004

"Code readability isn't about operators, it's about comments, formatting, variable/function names, nesting, and flow of control."

This particular manager had a Visual Basic background, and my code on that project was in C++. His evaluation of it was thus based upon the extreme dumbing down of C++ so that, without any responsibility on his part, he could fully understand it - a lowest common denominator. So C++ features such as operator overloading, which can dramatically improve readability to someone versed in C++, confused him and were declared evil. In other words what makes the code readable to someone with knowledge of C++ is entirely different than what makes the code readable to someone without C++ knowledge.

Some languages like Perl, or meta-languages like regular expressions or XSLT, unavoidably have a learning curve, by design, because the power they encapsulate cannot be simplified without dramatically diluting their productivity and value. It is absurd to judge those languages based upon whether the lowest-common-denominator can understand them, as it would be absurd to have Jimmy Sixpack rate the readability of a medical journal, or Johnny Fairplay rating the merits of an advanced mathematics essay.

.
Thursday, July 08, 2004

If your manager's a dumbass, then he's a dumbass.  You can't judge C++ by VB terms, and that's it.  But that's a different problem than posted in the OP.

The point made by the person you quote is hyperbole, but it contains a lot of truth: namely, that coding for expressiveness that only experts will appreciate is a recipe for obfuscated, dense code.  For any construct you look at that's ugly and dense, the coder can simply say "but someone familiar with the idiom will think it's beautiful."

Someone with a bare understanding of the language, and without extra-linguistic hangups (like your boss with VB) should be able to understand at least 50% of the code, from the highest level stuff to about halfway down.  It may take an expert to really grasp the subtle details, but if a newbie can't come along and understand what's generally going on, then you're coding for experts, and the result is going to be ugly, dense, and difficult to understand for anyone else.

Justin Johnson
Thursday, July 08, 2004

This gets into a major problem area, because writing a script is a good deal different than writing an app, a proof of concept, or something even more complicated.  Scripts are just automations of things that many of us could do with the computer.  Applications, on the other hand, often interface with O/S-level drivers and functions.  Also, more complicated pieces of technology can't be easily described using anything (i.e. some sorts are pretty complicated).  If you don't have a science background (I don't believe I.T. and computer science are the same thing), or the necessary abstract thinking capability (i.e. those pesky managers), then perhaps that person shouldn't be involved with the project at that depth.

sir_flexalot
Thursday, July 08, 2004

And I assume that you know that operator overloading is often considered a stylistic sin in C++ just because it obfuscates the code with a semantically ambiguous construct.  Even an expert C++ programmer won't automatically know what Foo foo1 = foo2 + foo3 means, and will probably have to look for your comments in the source where you overloaded the addition operator to see what the result is supposed to be when you add Foos together.

Justin Johnson
Thursday, July 08, 2004

"And I assume that you know that operator overloading is often considered a stylistic sin in C++ just because it obfuscates the code with a semantically ambiguous construct.  Even an expert C++ programmer won't automatically know what Foo foo1 = foo2 + foo3 means"

Sigh. Such is the pitfall of arbitrary examples.

Having said that, you're perpetuating the lowest common denominator approach. How does an expert programmer know what any custom function in a program does beyond that absolutely superficial verbose naming? The simple fact is that he doesn't and ultimately he has to take his body of C++ knowledge and build upon it with some project knowledge to reasonably expect to understand the project.

First the lowest-common-denominator (LCD) people tried to convince use that no one should have to bother with understanding the project before undertaking to do changes. Now we're being told that they shouldn't even know the language.

.
Thursday, July 08, 2004

Such is the pitfall of straw men arguments.  The person you quoted wasn't arguing for anything remotely like you're arguing against.

He was saying that good, readable code should be conceptually accessible to people even if they know only the basics of the language.  That doesn't qualify them to change the code, it merely means that the code is as accessible as it can possibly be to others who have to work with the code.  The learning curve has the gentlest possible slope, rather than the steepest, as you would seem to have it.

If I were to argue a straw man against you, I would suggest that you want people to have to grasp zen koans of code that take a decade of meditation to achieve satori with the perfection that spews from your keyboard.  But I doubt that's what you're arguing.

Justin Johnson
Thursday, July 08, 2004

The idea that code should be readible to someone with no knowledge of computers is the same as the idea that schematics should be readible to someone with no knowledge of electricity.

There are readible schematics that are well laid out and designed and there are schematics that are chicken scratches that no one can make out. The same goes for code. The only person qualified to judge whether code is readible is someone who is reasonable skilled in the craft.

It's lunacy to suggest code should be readible to the general public and spending time making code this way is wasteful when that time could have been spent making the code more understandable to another practictioner - someone who is far more likely to be the one who would benefit from doing so than that man on the street.

David Histerhoff
Thursday, July 08, 2004

Rather than saying code should be accessible to someone without a good understanding of the language, I would submit that it should be easily understood by a person without thorough knowledge of the project. For example, the more circular dependencies and global data you have in the project, the harder it will be for someone new to the project to start locating and fixing bugs. The same goes for badly named functions, "magic numbers" and string literals, and so forth.

Operator overloading can be very useful in making the code easier to read and understand. Conversely, it can also make what the the code actually does less obvious. Anybody who unilaterally decides that every instance of X is bad is just being ignorant (like that other thread where a programmer decided that database fields must never be null).

Derek
Thursday, July 08, 2004

> how long would it take someone who spoke english, but has never seen a computer in their life, to understand the code

I reckon that equates to "whether the source contains sufficient Enlish-language comments".

I like the comments to state what the code is doing (or is supposed to be doing), and the code to explain how it's doing that.

I'm a believer in the 'PDL-to-Ccomments' technique described in version 1 of _Code Complete_.

Christopher Wells
Thursday, July 08, 2004

"Such is the pitfall of straw men arguments.  The person you quoted wasn't arguing for anything remotely like you're arguing against."

Did you actually read the context of the discussion? The subject of the OP was advocating that

StaticClass.Method()

Is too confusing, and throws off someone. Do you _really_ believe they believe a practitioner of development is thrown off by this?

.
Thursday, July 08, 2004

"I reckon that equates to "whether the source contains sufficient Enlish-language comments".

I like the comments to state what the code is doing (or is supposed to be doing), and the code to explain how it's doing that."

This is an entirely fair comment, and for example if someone has a complex regular expression (because regular expressions can be quite obscure if you don't know regular expressions), I'd like to see something like

// Pull out the area code, exchange and number from the source
// form (AAA) XXX-NNNN

However the commenter wasn't talking about comments, they were talking about code, about such utter trivialities of code (like namespace or static class prefixes) that it is absolutely the supreme dumbing down of software development. When he talks about a non-programmer reading the code, it is literal.

.
Thursday, July 08, 2004

Isn't that like expecting my cardiologist to explain everything there is to know about reading EKGs to me when I visit him.

I don't expect him to dump years worth of knowledge just to talk down to my level.  Nor would I expect someone who doesn't know a byte from a bit to do the same to me.

5v3n
Thursday, July 08, 2004

> Isn't that like expecting my cardiologist to explain everything there is to know about reading EKGs to me when I visit him.

No, that's what the comments in the code are doing: explaining things in English.

Apparently what's being asked for is "worse": they're asking that the EKGs be presented in a format that let *you* (not the cardiologist) read them.

Perhaps it's (theoretically) possible to do that: you run the EKG signal through an expert system that inteprets the EKG and outputs the results for you in English ... I'm not sure why that isn't possible with software ... perhaps because the size of the "language" expressible with EKG is smaller than the size of the language expressible with software (e.g. only 70 cardiac conditions, compared with zillions of software applications).

Back on topic, what the difference between the "static import" (being discussed) and C#'s "using namespace" statement?

Christopher Wells
Thursday, July 08, 2004

Static import is the idea of your class sideways deriving the static members of a class, so if classA exposes the static member Sin(), you can static import it into classB so you can simply call Sin() rather than classA.Sin().

This would similar to if namespaces contained root level functions (i.e. they didn't have to be members of classes).

.
Thursday, July 08, 2004

I think that Darren's comments may have been misinterpreted in this thread.  My interpretation was not that he really expected non-programmers to read the code, but that, if code is easier to read, that benefits _programmers_.

For instance

  x = Sin(y)

is easier to read than 

  x = Math.Sin(y)

You think to yourself, "I want to find the sine of y", you don't think to yourself "I want to find the Math sine of y".  The point being that the more closely the code matches what we're thinking, the easier it will be to work with.

On the other hand, Eric Gunnerson did post a fairly presuasive counter-argument on his blog.

John Rusk
Thursday, July 08, 2004

This is a tough call. I write a good amount of Perl.

There is plenty of obscure Perl around, and I have written some.

So the question, how hard to push a language to make full use of the features, while sacrificing legibility for the non-expert?

dot for this one
Thursday, July 08, 2004

Who cares if non experts can't read your perl code? They shouldn't read it if they are non-experts.

Matthew Lock
Thursday, July 08, 2004

"Who cares if non experts can't read your perl code? They shouldn't read it if they are non-experts."

I'm not sure if you're trying to be sarcastic (I suspect you are), however what we're really talking about isn't "expert versus normal", we're talking about "marginally competent versus has-some-general-idea-that-language-exists". Perhaps because of the .COM boom, we have such a bunch of marginal programmers in this profession with such ridiculously superficial knowledge of languages and technologies, and we believe that we have to cater to them without any demands. Spend the god damn 4 hours and read a "Language for Dummies" book.

.
Thursday, July 08, 2004

If you want code that reads like English your ideal language would be... Cobol.

Case closed.

Chris Nahr
Friday, July 09, 2004

Chris, we are not talking about a language that reads like English, we are talking about it being comprehensible in English what your program DOES.

So, you make sure the documentation explains the general idea, where the language is obscure.

Clarity isn't 'dumbing down'.

Stephen Jones
Friday, July 09, 2004

Stephen,

Comments or documentation are hardly relevant to the discussion. You can document code in any language, so what would be the point of discussing the language at all?

Also, I wasn't talking about dumbing down but about being extremely long-winded. Conciseness brings its own clarity, and anyone who is programming a computer can be expected to have some basic grasp of mathematic expressions.

The clearest language wouldn't be one that you can grasp just with English skills (that would be Cobol) nor one that is just a string of mathematical symbols (that would be APL or obfuscated C++) but rather one that has "just the right mix" of the two extremes.

Incidentally, I think that most widely used languages today already meet this criterion, depending on which side of the middle point your tastes fall (usually begin/end vs curly braces).

Chris Nahr
Friday, July 09, 2004

*  Recent Topics

*  Fog Creek Home