re: Language Readability vs. Writability

Kevin Dente — Thu, 01 Jul 2004 21:10:00 GMT

Hey, while you're at it how about automatically inserting type specifications when declaring in-line arrays. E.g. "{1,2,3}" becomes "new int[] {1,2,3}". :)

re: Language Readability vs. Writability

jaybaz [MS] — Thu, 01 Jul 2004 21:16:00 GMT

Kevin: I'll check it out.

Readability vs Writability

stevencl's WebLog — Sat, 03 Jul 2004 01:52:00 GMT

re: Language Readability vs. Writability

Jeremy Marsch — Fri, 09 Jul 2004 19:24:00 GMT

I hope I'm not too late on this comment. In terms of readability vs. writeability, our shop went with readability to extreme ends.

We require that all type names are fully qualified (we don't use the using statement for aliasing namespaces). So, all variable/parameter/return value declarations are fully qualified. We also preface all member items with this. when we refer to them.

The refactoring stuff in the editor looks really exciting. Is it possible to have an options to tell the editor to always use fully qualified type names and to use this. in the code that it writes on our behalf?

re: Language Readability vs. Writability

jaybaz [MS] — Fri, 09 Jul 2004 19:44:00 GMT

Never too late!

Jeremey: We'll use the FQN if the 'using' directives aren't there. So, I think you'll be happy with the outcome.

re: Language Readability vs. Writability

Darren Oakey — Tue, 13 Jul 2004 00:37:00 GMT

Hmm.. I think this is an odd post, because in all the explanations and examples, you've assumed something which I is not just "not necessarily true" - bust is actually rarely or even never true,
... that is - you've assumed for some reason that more information==more readable.. That's completely untrue - in fact, more irrelevant information decreases readability.

Why?
Well, when you are reading or maintaining code, what is most important is understanding THE INTENT of the code. It is NOT even vaguely important, in the first few runs through, to understand THE MECHANICS of the code. For example:

> Console.Writeline( Square(5) );
compared to
> Console.Writeline( Square<int>(5) );

We read the first example, and we understand completely. You say it's not obvious WHICH console.Writeline is called, but I would argue that you neither NEED nor WANT to know. Anyone who tries to understand the underlying libraries at the same time as the piece of code they are actually investigating is a) doing a lot more work than they should and b) feeding too much information into our very limited brains, thus == confusion.

What you need to know is that 25 will appear on the screen - you don't need to know HOW. (unless there is a bug, you are confident Square works, then you can go and right click and go to definition, and try to track it down). But the main point is, the function is actually more readily understood _without_ knowing which overload you are calling (or that the base function is actually overloaded at all.

That's why I have a problem with all the examples above. They focus on the unimportant information that is being shown (type specifiers and the like)... That's hungarian thinking... But the examples don't have real variable names, which is where readability actually needs to come in. For instance I would shoot anyone in my team who wrote

> foreach (i in foobar(x))

That's just bad coding. But do we make the same conclusions about readability if we write it as it would actually appear - eg:

> foreach (employeeToCancel in theSetOfRetrenchedEmployees)

is it any more readable to see

> foreach (Employee employeeToCancel in theSetOfRetrenchedEmployees)

I'd say no. It's just like people say of comments - comments should say what the code INTENDS, not what the code DOES - people can just read the code for that. The same thing with things like type inference etc - a good coder will always make that sort of thing obvious anyway - for instance we have an absolute unbreakable rule that no function (including the comments header) can be more than 25 lines... which means whenever you are looking at a function, you can ALWAYS see the whole function - so always SEE the type definitions and so forth. Having them repeated on the lines underneath is just redundant and unclear.

One more example - how much more readable is

> ShowColorChartsFor( {Color.Green, Color.Red, Color.Blue } );

compared to

> ShowColorChartsFor( new Drawing.Color [] {Color.Green, Color.Red, Color.Blue } );

The latter gives you more _information_ but that information does not actually help your _understanding_ of the functionality, in fact it hinders it..
Chomsky in his studies on human learning explains a phenomenon called blocking, which says that expected or redundant information actually inhibits comprehension [for instance if you show a kid the written word tree, and say "tree" - they will learn it, but if you show them the word tree near a picture of a tree, they will NOT learn it - because our brains are lazy and focus the easiest think they can - the kid knows the link between the picture and the spoken word, so do not need to form a link between the written word and the spoken word]

In the same way, in the lines above, your brain will zip off in a tangent thinking about the construction of a string array, and miss the point, which is that you are trying to show color swatches for the colors red, green and blue. It is very important in code that we try to get the _mechanics_ out of the syntax/out of visibility as much as possible, so people can focus on the _intent_.

re: Language Readability vs. Writability

jaybaz [MS] — Tue, 13 Jul 2004 00:45:00 GMT

Darren: very interesting. Thanks for taking the time to write it all out.

It'll take my brain a little time to process, for sure.

Oh, and +2 points for referencing Chomsky. :-)

jaybaz MS WebLog Language Readability vs Writability | My Site

jaybaz MS WebLog Language Readability vs Writability | My Site — Mon, 01 Jun 2009 06:57:54 GMT

PingBack from http://patiochairsite.info/story.php?id=306