Braces and Indenting: You’re Doing it Wrong

Screen Shot 2014-01-28 at 8.33.08 AMJava, C++, Objective-C, and C# all use braces ( { and } ) to delineate the beginning and end of blocks of code. Over the years, several styles have evolved, with the worst of them dominating the literature. Once you see The Light you’ll wonder how we ever let this get out of hand.

Before we begin, let’s remind ourselves what braces are for: They mark the beginning and end of blocks of code. In many contexts a block stands in place of a single statement. It allows us to put two or more statements in a place where a single statement is called for in the grammar. In those contexts a block is functionally equivalent to the single statement it replaces. This will be important in our understanding of the One Right Way to indent.

In other contexts, such as the bodies of functions, surrounding the cases in a switch statement, and surrounding the declarations in a class definition, braces demarcate the contents of the function, switch, and class. For convenience, I’ll refer to any group of lines of code surrounded by braces as a “block”, even though the language definition may not always use that term in every context in which braces are used.

So the the first question is to ask: “To what do the braces belong: the block they surround or the syntactical element (if, for, switch, class etc.) to which the block belongs?”

When braces are used to surround a true block (the else clause of an if statement, for example), it’s clear the braces belong to the block. Together with the lines of code they contain, they replace a single statement.

The implication is that the braces should be indented at the same level as the lines of code in the block they surround, for they are part of that block.

The second question we need to ask is: “Should braces share the line with any other code; either a statement from the block they surround or the statement the block belongs to?”

Clearly we would not format code like this:

    x
    = y
    +
    z
    ;

We might break a very long line into two or more lines, but a short statement should always be on one line. Similarly, we try to avoid code like this:

    x = y + z; if ( x > 10 ) foo(x); bar(z); switch (y) {case 1: x = 2 * y; break; case 2: default: foo(x); break;}

The commonly accepted practice is to put one statement on each line. (There are exceptions but they are rare.) Similarly, I would argue that braces belong on a line by themselves. They are not “inline operators” like + or ==. They do not belong to the statement to their right or left; they surround those statements.

The reason we don’t put two or more statements on one line is that it is more difficult to read. It’s why we break up our thoughts into sentences and paragraphs. It aids in comprehension. The same is true of code. Consider the following:

    if ( x < 10 ) { foo(x);
        bar(y); }

The call to foo(x) belongs to the then-clause because it is inside the brace but it would be easy to glance at the code and assume bar(y) is the only statement executed when the if-condition is true because the call to foo(x) is “hidden” at the end of the if statement.

For this reason I would argue that braces belong on a line by themselves. It is too easy to miss them when they are “hidden” at the end of another line of code. So unless you’re in the habit of writing a dozen statements on one line, it doesn’t make sense to put a brace on the same line as another line of code.

With these two rules (i.e. braces belong to the block they surround and braces belong on a line by themselves), there’s only One Right Way to indent your code:

    if ( x < 10 )
        {
        foo(x);
        bar();
        }
    else
        {
        x += 10;
        foo(x);
        }

Now we can see why the predominant indenting style is so, so wrong:

    if ( x < 10 ) {    // should not be on same line as "if"; should be indented with block
        foo(x);
        bar();
    } else {              // should not be on same line as else (*2); should be indented like block above/below
        x += 10;
        foo(x);
    }                     // should be indented like block above

I realize those of you who grew up doing this wrong and reading all the literature from others who do it wrong will find the One Right Way more difficult to read. But it can be argued that you only find it difficult to read because you’re not accustomed to doing things the One Right Way, while the wrong style as illustrated above is difficult for me to read because it makes no attempt to be logically consistent. This makes it objectively wrong, not just a matter of personal preference.


Postscript
In the spirit of unity and the cause of world peace, practitioners of the One Right Way will accept the following style with the hope that those practicing it will see the one small error in their way and with proper mentoring and encouragement, will correct it:

    if ( x < 10 )
    {
        foo(x);
        bar();
    }
    else
    {
        x += 10;
        foo(x);
    }

An eCommerce Company Wants to Know: Do I Want to Double My Sales?

While searching for something else in my email archives, I ran into this exchange with a sales rep from Digital River who spammed me a few years back asking if I wanted to double our online sales. It’s rather humorous.

Subject: Online Sales @ Laridian

Hi Craig,

How are sales from laridian.com? If we could double online revenue, would you be willing to outsource your web store to Digital River? We have done this for most of our 3,000 software clients and would welcome the opportunity to discuss how we may be able to do the same for Laridian. Please reply if your willing to consider outsourcing your online store.

Sincerely,
John S
Regional Sales Manager
Digital River, Inc.
www.digitalriver.com

Wow. That sounds great. I’m always up for doubling my revenue. Here’s my respose:

From: Craig Rairdin [mailto:craigr@laridian.com]
To: ‘John S’
Subject: RE: Online Sales @ Laridian

Hi John!

Sales are great! No reason to make any changes. But you sound like an honest man so I’m willing to simply take you at your word — if you are willing to stand behind it.

Write back if you’re willing to sign a written guarantee that you’ll double our net revenue from Web sales as you’ve claimed you can do in your email.

Of course once we move to Digital River it will be difficult to say what our sales would have been had we not moved, so what we’ll do is take the last three years of sales and find a best-fit line based on monthly net revenue (i.e. revenue less cost of sales). We’ll project that line over the next three years and you will guarantee to send us a check for twice that amount regardless of your actual revenue from our products. At the end of three years we both can decide whether or not we want to continue the relationship.

One-half of each month’s guaranteed payment will be due on the first of the month. The remainder (either the other half of the guaranteed amount or the actual net revenue from sales) will be due within 10 days of the end of the month. If you don’t pay the full amount due in a particular month within 10 days of the end of the month, then we revert back to selling ourselves and the remainder of the 3-year contract becomes due immediately.

I don’t expect to have any expenses associated with the conversion from doing this at our site to doing it at yours. I anticipate that the way the changeover would work is that you would get everything set up on your end at no expense to us, then on the first of some particular month I’d find a check from you equal to that month’s projected net revenue and I’d edit a few lines of code on our site to send customers to your site for ordering, or we’d make a DNS change that would redirect our entire site to your servers.

I don’t expect to have any marketing expenses associated with driving traffic to the site. You’ll handle our online and print advertising as it relates to direct sales. Of course we’ll continue to handle marketing and sales through other channels.

John, I assume you’ve done your homework and you have a rough idea how much money you’re committing your company to, or you wouldn’t have made such claims in an unsolicited commercial email. Of course I trust you implicitly and know that you wouldn’t say something like this if you weren’t fully willing and able to deliver. It must be great to work for a company that can deliver these kind of results! Frankly, I’ve been looking for a Magic Bullet that would double net revenue from our Web site. If you’re willing to stand behind your marketing claims with real money (and I have no reason to doubt that you are), this could be a match made in heaven!

Craig

I assumed that if John was bold enough to claim he could double our online sales that he actually believed he could triple or quadruple them. Otherwise, he’d risk not being able to hold up his end of the deal. So my plan to hold him to his (outrageous) claims should’ve been a no-brainer for him. Apparently not. Here’s his response:

From: John S
To: Craig Rairdin
Subject: RE: Online Sales @ Laridian

Hi Craig,
You sound like a smart business man, so I’m sure you already realize their are no guarantees in business. It is true we have been able to double online revenue for most of our clients, but I’m sorry you misunderstood my email.
Regards,
John

What? I misunderstood that when he said he could double our sales, he meant that he couldn’t double our sales?

From: Craig Rairdin [mailto:craigr@laridian.com]
To: ‘John S’
Subject: RE: Online Sales @ Laridian

Hmmm… So when you said “If we could double online revenue, would you be willing to outsource your web store to Digital River?” you never intended to demonstrate your ability to do that in any concrete way? You asked if we’d outsource our store in exchange for double our current revenue, but you had no intention of proving you could do it or standing behind your promises with guarantees.

So what are your potential customers supposed to do? Just believe a guy who spams them and turn over their life-blood to his company with the hope that the spammer knows what he’s talking about? You may have found 3000 other nut-cases with this pitch but you didn’t find one here.

Even though my message was tongue-in-cheek, I’d be willing to actually follow through on the promises made therein. By contrast, your message was a serious invitation to do business together, but you had no intention of standing behind your words with any kind of concrete action. Your willingness to spam me and spew nonsensical marketingspeak with no intention of delivering tells me more about Digital River than you could possibly imagine.

Please remove us from your spam list.

Craig

To his credit, he removed me from his spam list.

I think a business that makes a clear claim in a solicitation for business should be willing to stand behind it. I think my proposal was more than fair, even though I knew he would never go for it. It irritates me when a business makes claims like this and thinks they shouldn’t be held responsible for them.

A Customer Wants to Know: How Stupid Can I Be?

Back in the day, we used a number of email lists run by a program called mailman to communicate with our customers. You could join a list based on the type of device you had, and from time to time we’d email you to let you know about updates and upgrades. We stopped using these lists around 2007 but the server is still running.

Every month, the list server sends each member his password and a reminder that he can unsubscribe or change his preferences by logging into the server and making the changes. When you sign up for the list, you can turn this option on or off. Because so many people sign up by email and have a password generated for them automatically, this behavior (monthly reminders) is turned on by default.

On January 1 I received this email from a subscriber to our iPhone list. I’ve changed his name and anonymized his employer’s company name, which appeared in every email he sent. Note he’s writing from the UK.

You have just emailed me my user name and password in an e-mail in plain text.

Are you stupid or something!

I have closed my account

Jimmy McWeenie

Jimmy’s Employer’s Name Here

Normally, I would send a nice response that explains that there is no financial or personal data exposed by the password, and would explain why we enable this behavior by default. But his “are you stupid” comment irritated me. I crafted a number of more- and less-tactful responses to this email, but ended up sending this one:

On 01/01/2014 15:09, “Craig Rairdin” <craigr@laridian.com> wrote:

Jimmy,

When you signed up for this email list, you chose the option to have the server send your login credentials to you every month. We are stupid enough to send you the information that you requested on the schedule that you requested.

We’re also stupid enough to send you the products you purchase and stupid enough to respond to your support requests. We’re stupid enough to continue developing new products for new platforms and stupid enough to give them away for free.

I hope we’re stupid enough to explain this clearly.

Let me know how much more stupid you need us to be.

I hope your new year is off to the same great start that ours is.

Craig

Jimmy replied:

If you still don’t get that sending someones login details, their user name and password in plain text in an e-mail is not just stupid, it’s a breach of the Data Protection Act 1998, then you should be involved in the computer business at all.

You don’t send this data out every month, just four times since 2011, which was when I had a look at your software.

I’ve done my best to ensure that my account with you is now closed, hopefully be can now both enjoy a 2014 equally undisturbed by each other

Best wishes

Jimmy McWeenie

Jimmy’s Employer’s Name Here

I had to look up the “Data Protection Act of 1998”. It was at this point I realized Jimmy is in the UK.

On 1 Jan 2014, at 22:54, “Craig Rairdin” <craigr@laridian.com> wrote:

Jimmy,

Our company and our server is in the US. We haven’t been subject to the laws of the UK since the late 1700’s. 🙂 This is an email list you signed up for. When you signed up, you had the option to have your login credentials sent to you every month. You chose that option. The list server is following your instructions.

Every mailman list server list from the beginning of the internet has done this. I get these reminders every month from a dozen lists. I’m glad to hear you figured out how to remove yourself from the list, which is one of the options that is presented to you every month. You have not “closed your account” — just removed yourself from an unused mailing list.

I’m working on that particular server today and will shut down all the lists while I’m there. We haven’t made use of them for a long time and most people have removed themselves already.

Craig

Jimmy replied:

Unfortunately Craig, you are wrong again. Your company is currently offering it’s products through Apples UK App Store, and so those accounts will be liable to UK taxes and jurisdiction.

I very much doubt that any one who signed up, expecting some kind of news letter, thought that you would e-mail out their account details in plain text.

Tell you what, I’ll e-mail our conversation around to a few websites tomorrow, and we’ll see if, generally, people think that your company is behaving irresponsibly or not.

I’ll cc you in so that you can know who I’ve sent them to, as no doubt they will want some comments from you

Regards

Jimmy McWeenie

Jimmy’s Employer’s Name Here

So now Jimmy is threatening to expose this vile breach of privacy to the rest of the world. My experience is that people who make this threat either never follow through, or else the people they notify are used to receiving their crazy rants and just block them. So I’m not worried. Continuing to demonstrate the scope of my stupidity, I chose to respond:

On 2 Jan 2014, at 00:00, “Craig Rairdin” <craigr@laridian.com> wrote:

Our relationship with Apple is one where they act as an independent seller of our software. Our agreement with them makes them responsible for all taxes and local laws in the places in which they do business. It does not create nexus in the UK for Laridian. In fact, one of its purposes is to assure us that it is Apple that is doing business in the UK, not us. The people who signed up for the list learned about the purpose of the list on the same page where they opted to have their password emailed to them every month. If they knew they were signing up for a newsletter, they knew they were requesting their login credentials. And if they objected to receiving those, they read the instructions and learned, just as you did, how to remove themselves from the list or change their subscription settings.

Feel free to pass our conversation around to whomever you feel it would benefit. Make sure to let them know that we sent you the information you requested, that we told you how to stop receiving that information, and that you followed those instructions and now are not receiving that information any longer. If that angers them to the degree it does you, I’d be happy to discuss it further with them.

Craig

This morning, Jimmy replied:

On 1/1/14 6:13 PM, “jimmy mcweenie” <jimmy@jimmys_employer.co.uk> wrote:

I’m sure that Apple will be one of the people I send this to. From a brief viewing of Apples terms and conditions, it would seem to me that they make some effort to preclude the type of liability you suggest falling on them. Would you like to take the opportunity, right at the start, to send me a copy the details of where I signed up to have my account information sent to me in plain text? You seem to want to rely on the fact that I asked you to do this, and you were only complying with my wishes.

If you send me evidence that I specifically asked you to email me my account security information as plain text each month, I will include this information with my email of this conversation.

Is there anyone at Laridian you would like to involve in this discussion?

Regards

Jimmy McWeenie

Jimmy’s Employer’s Name Here

By threatening to involve other people at Laridian, he’s hoping to get me worried that my boss will find out how I’ve been treating our customers.  Clearly, Jimmy hasn’t read the Laridian org chart. When it comes to stupid, I’m the top dog here. I decide to bring this to an end.

On 02/01/2014 16:40, “Craig Rairdin” <craigr@laridian.com> wrote:

Here’s the documentation for Mailman, our list manager software: http://www.gnu.org/software/mailman/docs.html. It contains everything you need to know.

You may involve as many people in this discussion of the subtle details of your email preferences as you think will be interested. Personally, I’ve lost all my interest. I have explained the situation to you; you have removed yourself from the inactive list you signed up for; I have removed you from any future email we may do (though we probably haven’t sent you a marketing email in the last 10 years or so); and I’m in the process of shutting down this unused mailing list server. I’ve disabled the automatic monthly emails, which is irrelevant since I plan on having the entire physical server offline in the next few days.

I have explained that we’re not subject to the Data Protection Act of 1998 since we have no nexus in the UK. Furthermore, the mailing list does not retain any “sensitive personal data” as defined by the Data Protection Act of 1998, so unauthorized acquisition of your password would not expose any data that is protected by the Act, even if we were subject to it.

This will be my last email to you on this subject, which, as you so tactfully put it, is “How stupid can (I) be.” I believe I answered that question by simply replying to your email. I made it clearer by continuing the conversation as long as I have.

Again, I wish you the very best for the new year.

Craig

But Jimmy will have none of it. He continues:

Craig

In a mission to prove how stupid you really are, you decide to have one last poke at me, when I hadn’t taken my complaint any further.

I had decided that in light of the fact you sold Bible software, I would put the exchange to a down to a bored techie whiling the time away making ill advised comments to a customer.

However if you want to discover how serious this complaint is, I’m e-mailing Apple to see what they think of Laridian distributing customer account details across the weld every month

Enjoy

Regards

Jimmy McWeenie

Jimmy’s Employer’s Name Here

So sometime between when he said he was “sure” he was going to send this all to Apple and when he received my reply, he decided not to. Only when I replied did he decide to cry havoc and let slip the dogs of war. Interestingly, my reply contained no “pokes” at him, only a continuation of the self-depricating theme of answering his question “How stupid are you?” in the affirmative.

I’m sure since Jimmy has no idea that I’m the President of Laridian that he has no idea who to send his email to at Apple. I’ll let you know what happens next.