The definitive guide to whitespace, part 1



All timestamps are based on your local time of:

Posted by: stak
Tags: code, whitespace
Posted on: 2009-03-10 23:17:14

Part 1: method invocations

The rules

  • Arguments in favor or against any of the options must not be based on subjective viewpoints (e.g. "it looks prettier").
  • Mention of languages that do not follow a C-style syntax is strictly prohibited (to avoid flame wars).


The options

optionA(foo, bar, func(baz));
optionB( foo, bar, func( baz ) );
optionC (foo, bar, func (baz));


The arguments
Option A is the shortest, requiring the least amount of typing, and fastest compilation time.

Options A and B have no whitespace before the opening parenthesis, therefore requiring a shorter search string when looking for instances of the method invocations (i.e. grep "optionA(" instead of grep "optionA (").

Option B is most convenient for manipulation via a tool (such as a naive code preprocessor), since useful tokens can be obtained by splitting the code on whitespace. Option A would return things like "optionA(foo," which are less useful than "optionB(" and "foo," separately.

The conclusion
To be determined once y'all weigh in with additional options and arguments.

Posted by Eric at 2009-03-11 08:30:23
OptionC fails to semantically group the arguments with the call, so it's out.

Some will argue extra whitespace in OptionB makes for better readability. They are wrong. Again, when I read it quickly, it fails to semantically group arguments. The call to func just looks ridiculous.

So OptionA is the only one that makes any sense.

I am using my background in typography when I say "semantically". Unexpected whitespace is cognitively jarring. No one would write English like OptionB, and in OptionC, the space between the name of the function and the items in parentheses indicates a separation of ideas, which is what you don't want.

Isn't everyone taught OptionA anyway?
[ Reply to this ]
Posted by stak at 2009-03-11 09:03:36
Perhaps I didn't specify "subjective" clearly enough. By "subjective" I mean any argument that relies on any sort of individual preference, such as your argument to exclude option B. I will even exclude arguments that rely on probabilistic preferences ("3 out of 5 people prefer x").

Your argument for OptionC is borderline, but I think still subjective. You say unexpected whitespace is cognitively jarring but there's an implicit "for me" at the end of that. You might be able to reformulate that one to be more objective.

And it doesn't matter what people are taught. Most of what we are taught is wrong anyway.
[ Reply to this ]
Posted by Eric at 2009-03-11 10:13:51
If those are going to be your rules, I'm not sure we're going to get anywhere.

The only objective source I have for the laying out of text is the rules of typography, and they say putting spaces between things means they are two separate things. If there's two things with a space in the middle that I have to think of as one thing*, that's cognitively jarring because one can't use the same heuristics applied to all other reading. OptionC seemingly slain by the rules of putting words on paper/a screen.

(* - You might be thinking of "fire truck" or similar as a counterexample, but that's still two things, one a noun, the other an adjective modifying the noun. Think instead of an unexp ected space in a word or a paragraph

break in the middle of a sentence.)

Whitespace is going to be a subjective thing no matter what. Decades later, people can't decide on one way lay out their braces to denote code blocks. Or which kind of paradigm is superior in a text editor. This strikes me as the same problem: people like different things, and they're going to choose the one they like the best, and no matter what they choose, someone will come along with arguments that boil down to "UR DOIN IT WRONG"

I can see people who might like optionB. It strikes me as time-wasting frippery, but if you want to lay out your code that way, go nuts.
[ Reply to this ]
Posted by stak at 2009-03-11 20:04:11
We might not get where you think I'm going, but we should get *somewhere*. Note that I'm not trying to convert the masses to switch. Better people have tried and failed at that; I have a different solution to that particular problem.

However, I would, for my own benefit, like to determine the best programming practices. Ones that result in the highest possible quality of code. There are simple idioms you can use in how you write code that makes it more robust against error. I'm looking for analogous practices when it comes to visual layout of code.

I'm also dismissing all arguments that are based on "readability" because I believe that if you use a particular coding style, it becomes more and more readable to you as you get used to it. Given enough time, even OptionC (which I admit looks really weird to me right now) would look natural. Since all coding styles are therefore equally "readable" in the long run, I'm only considering things that have a functional benefit. Apologies if that offends your sense of typography, but that's what I care about.
[ Reply to this ]
Posted by Eric at 2009-03-11 21:29:10
I think I see what you're trying to drive at, but I don't believe there's one way to visually lay out code that necessarily makes one a better programmer, if for no other reason than if there was, we'd be doing it by now.

Parsing? Lexing? Bah! The Code Monkey cares not for the concerns of the Compiler Guru. They want different things out of a language (people love perl, but no one wants to rewrite a perl compiler). I don't care which is easiest to write a compiler for; that only has to happen once.

And since you don't care about readability (which strikes me as the only tangible thing visual layout of code impacts), I don't see anywhere to go.
[ Reply to this ]
Posted by stak at 2009-03-11 22:09:23
I don't buy that argument. By induction you could say that we've already discovered everything there is to discover. And anyway, I would rather waste time in an attempt to find a better code layout and fail than assume there isn't one and sit around on my ass twiddling my thumbs.

What about the arguments I gave in the post? Are those not tangible benefits that are independent of readability?
[ Reply to this ]
Posted by Alex McCarthy at 2009-03-12 01:14:27
"Programs must be written for people to read, and only incidentally for machines to execute." - Abelson & Sussman, Structure and Interpretation of Computer Programs

When I write code, I try to make it as readable as possible (or that's what I tell myself). How the machine deals with what I've written is an afterthought.

In general, I prefer human-friendly coding choices over computer-friendly choices. The increasing popularity of high-level programming languages (machine language -> C -> C++ -> Java -> Python) would also imply that humans are code's target audience, not machines.
[ Reply to this ]
Posted by stak at 2009-03-12 07:25:56
I agree wholeheartedly that code must be readable before all else. I'm not disputing that in the least. What I am disputing is your assumption that one style of coding is inherently more readable than another, and that it will remain so for all of eternity. That is simply not the case. To me right now, options A and B are equally readable. Given a month or so, option C would be just as readable. I have no control over what other people find readable, so conforming to most readable style overall is pointless. The only logical action is to find the most useful style, and then *make* it the most readable as well for myself.

Incidentally, you seem to also assume that readability and functionality are mutually exclusive. They are not. For instance, being able to search for a particular piece of code and finding it before you get distracted or lose your mindspace is critical to readability. If the formatting of your code is such that it takes too long to find code, then that hampers readability.
[ Reply to this ]
Posted by Eric at 2009-03-12 08:17:44
By induction you could say that we've already discovered everything there is to discover.
That's a straw man. I'll buy you a goat if you're the first person to ever examine the layout of code by...what metric exactly?

I still don't see what kind of ruler one should be applying. You threw readability out. We've agreed that ease of compilation/lexing/parsing shouldn't enter in to it. Your post then mentions grepping and typing time. I don't believe that any one is easier to grep than any other, and people type at such different rates that typing time can't be an objective measure.

I'm out of this discussion. I'm now certain your investigations will be fruitless.
[ Reply to this ]
Posted by Varun at 2009-03-14 13:52:52
To be determined once y'all weigh in with additional options and arguments.

This is syntactically incorrect. "y'all" is the singular second pronoun, equivalent to the word "you". To refer to multiple people in the second person*, you have to use "all y'all".

And I abstain from voting since you're tossing readability concerns.

*: Interestingly, in older English, there was a difference between the singular and plural second person - "you" and "yous", respectively. Standard Irish English retained this difference (and Cockney resurrected it), whilst standard RP English dropped it.
Name:
Comment:
Allowed expansions in comments/replies: [i]italic[/i], [u]underline[/u], [b]bold[/b], [code]code[/code], [sub]subscript[/sub], [sup]superscript[/sup], [url=http://some.url]linked text[/url]
Human verification: Sum of fifty-four and thirty-five =
Posted by Fai at 2009-03-14 18:54:30
The definition I heard for "y'all" is different. I think it's plural second person, as in "what do y'all want for dinner".
As it was explained to me "all y'all" means each person in the group you're addressing. as in "did all y'all enjoy the movie".


what about:
optionD ( foo, bar, func ( baz ) );
[ Reply to this ]
Posted by Jon at 2009-03-15 12:48:43
"Y'all" is a contraction. It contracts "you" and "all": y'all = you all.

"What do y'all want for dinner?" = "What do you all want for dinner?" = "What do all of you want for dinner?"

"Did all y'all enjoy the movie?" = "Did all you all enjoy the movie?" = doesn't make sense. It's colloquial and I believe is used the same was if the first all wasn't there, but strictly speaking, the phrase is grammatically incorrect.
[ Reply to this ]
Posted by Fai at 2009-03-15 18:40:13
strictly speaking "ain't" is incorrect as well, but it still has a well understood meaning.

An arbitrary google search confirms my definition: http://memphis.about.com/od/midsouthliving/qt/yall.htm
[ Reply to this ]
Posted by rohan at 2009-03-14 19:10:25
Interestingly, in older English, there was a difference between the singular and plural second person - "you" and "yous", respectively

No, in early modern English the distinction was "thou" for singular and "you" for plural.
[ Reply to this ]
Posted by Varun at 2009-03-14 23:07:33
The dangers of learning about English from the Irish, illustrated ;)
[ Reply to this ]
Posted by Varun at 2012-04-29 15:17:27
I was reminded of this entry by this posting from The Verge. And yes, I still believe option C is the most human-readable, and thus must be the correct answer ("it's prettier"! etc).
[ Reply to this ]

[ Add a new comment ]

 
 
(c) Kartikaya Gupta, 2004-2024. User comments owned by their respective posters. All rights reserved.
You are accessing this website via IPv4. Consider upgrading to IPv6!