Coding Style Part 2

 By Shamus Jan 18, 2013 144 comments

splash_frustrated.jpg

As I mentioned in the last post, I read the Office document that describes the internal coding conventions of id Software, and I thought I’d go over it. This will be pretty familiar stuff for coders, but if you don’t program this might give you a glimpse of how strange and fussy this discipline can get.

I’m going go go through the standards guide and offer my own comments / explanations on why I think they’re interesting or important. The stuff in bold is from id, the rest is from me.

“Use real tabs that equal 4 spaces.”

Ah. The old “tabs vs. spaces” holy war. This one is probably as old as C itself, and may even pre-date it by reaching back into older languages. In C++, you’re expected to indent your code:

1
2
3
4
5
6
7
if (a < = b) {
    a = a + 2;
    if (b < a) {
      b++;
      a = 0;
    }
}

When you indent code, does hitting the TAB key insert a single tab character that moves the cursor to the next tab stop, or does it insert the number of spaces required to reach the next tab stop? You can set it to work either way, but you had better make sure you’re on the same page as the other coders. Let’s say you’ve got tab stops set to 4 spaces. If you’re using actual spaces, then internally your file looks like:

1
2
3
4
5
6
7
if (a < = b) {
....a = a + 2;
....if (b < a) {
........b++;
........a = 0;
....}
}

While tabs produce a file like this:

1
2
3
4
5
6
7
if (a < = b) {
.a = a + 2;
.if (b < a) {
..b++;
..aa = 0;
.}
}

See, compilers are primitive command-line programs. Sure, you might be writing code in a fancy windowed environment, but when you hit compile your source code is handed off to a text parser that’s blind to your decadent GUI interface. It has no idea what your tab stops are set to and it doesn’t care. It just counts whitespace characters, and as far as it’s concerned spaces, tabs, and all other non-printing characters look the same. So when it reports that it sees an error on line 5, column 3, (Variable ‘aa’ is undefined.) it doesn’t realize that for YOU the problem appears to be in column 12. I’ve never personally run into this problem, but I’ve read people complaining about it. I’m sure it all depends on what compiler / editor combination you’re using.

So, spaces must be the way to go, right? Except…

Spaces are fixed. If we use tabs then different coders can adjust things to suit their own preferences. I can set my tab stops to a sprawling eight. It will eat up a ton of horizontal space, but it will make the formatting very clear. Perhaps you will set your tab stops to a miserly two. You’ll have lots of information on screen at once, but you might need to squint a bit to follow the code when things get complicated. The point is, if we use tabs instead of spaces then we can each see the code the way we want to see it. You can even change how its displayed while you’re looking at it if you need more room or clarity.

Then again, if you’ve formatted something specifically using a given tabstop arrangement, it might fly apart under a different one. These diagrams:

/*-----------------------------------------------------------------------------
                          North                 N    
    *-------*           *---+---*           *---*---*     *---+---*
    |\      |           |\     /|           |\Nl|Nr/|     |   |   |
    | \ Sup |           | \   / |           | \ | / |     | A | B |
    |  \    |           |  \ /  |           |Wr\|/El|     |   |   |
    |   \   |       West+   *   +East      W*---*---*E    *---+---*   
    |    \  |           |  / \  |           |Wl/|\Er|     |   |   |
    | Inf \ |           | /   \ |           | / | \ |     | C | D |
    |      \|           |/     \|           |/Sr|Sl\|     |   |   |
    *-------*           *---+---*           *---*---*     *---*---*
                          South                 S      
-----------------------------------------------------------------------------*/

…would collapse into a soup of random characters if they were built with tabs and someone viewed them with the wrong settings. In a less outlandish example, doing non-leading formatting like this:

int foo            =10;
float foobar       =10.0f;
char foostring     ="10";

…with tabs will lead to tears and confusion when someone looks at it with different-sized tabs.

Then again, you could always use tabs when formatting code and spaces when drawing ascii diagrams or arranging stuff into columns. Then again AGAIN, mixing tabs and spaces is a great way to drive someone mad. When you traverse over whitespace using the arrow keys, you do not want to be in a situation where you don’t know if you’re passing over spaces or tabs. Inserting or deleting spaces mixed with tabs can feel jumpy and random in a way that leads to typos and swearing.

You’re free to argue the merits of tabs over spaces, but there’s no disputing that the worst thing to do is mix them together.

codingstyle1.jpg

Oddly enough, I always use spaces even though I think tabs are better. I spent a decade working in a Thou Shalt Not Tabbify environment, and now when I traverse tabbed code the cursor-jumps make my eye twitch. Like learning to play an FPS with mouse inverted, it would have been better if I’d learned the other way but changing now would be prohibitively difficult. I’d stumble through tabs if it was part of earning a paycheck, but if I’m working alone on my own projects I’d just as soon be comfortable.

A non-programmer might ask, innocently enough, “Why don’t you just convert the tabs to spaces? One person uses spaces, then you can change them to tabs before you use the file. It should be easy to write a program to do it for you.”

Indeed this is easy. In fact, I think most environments have this sort of thing built in. In some environments it may even have a handy keyboard shortcut. Just select all and click “auto-format” or “tabbify” or whatever. The problem here is that we use revision control (or whatever the kids are calling it these days) to manage changes to all of these multi-author text files. To make a change, you “check out” a file, similar to checking a book out of the library. You make changes to the file, and then you check it back in*. The system will then offer the other coders a nice summary of what changed. They can see, line-for-line, what was added, removed, or altered. However, if you re-tab an entire document, then every indented line of the file will be different, which will make it appear as though you re-wrote the whole thing from scratch. The resulting chaos would be worse than the problem you were trying to solve.

* Note to coders: Do NOT nitpick me with merged changes, forks, branches, and other complexities. I’m just trying to throw a life preserver to the non-coders, and I don’t need you weighing it down with a cinderblock of source management theory.

“The else statement starts on the same line as the last closing brace.”

The guide is talking about doing this:

1
2
3
4
5
if (a < b) {
    biggest = b;
} else {
    biggest = a;
}

Instead of this:

1
2
3
4
5
6
7
if (a < b) {
    biggest = b;
} 
else 
{
    biggest = a;
}

I have no idea what madman decided the second was a good idea. In a complex block of code, this can throw away a ton of screenspace, and I don’t think it improves readability at all. This seems to be a page from the “things are less confusing if there’s less information on the screen” school of thought. This is an understandable sentiment in certain situations where you might find yourself daunted by walls of unbroken code, but let’s not build a coding convention to make all else statements take three whole lines of code for no reason. Spacing code out too much means you can’t see very much at any given time, which results in tunnel vision.

I’ve always suspected the three-line else (like other screen-devouring conventions) was invented by people who got paid by the line of code. According to programming lore, there was a time when managers would measure programmer output by how many lines of code they’d written. This was ostensibly a real thing done by human beings who were at least smart enough to operate a necktie. The quote “Measuring programming progress by lines of code is like measuring aircraft building progress by weight,” is attributed to Bill Gates. This was back in the days when Microsoft was a smallish company and they were making software for IBM, who purportedly liked to measure progress in this way.

“Pad parenthesized expressions with spaces”

We’re talking about this:

1
2
3
if ( a < b ) {
  DoSomething ( a );
}

Instead of this:

1
2
3
if (a < b) {
  DoSomething (a);
}

This is the first one that I’m really not crazy about, and given the type of work they do I’m kind of surprised id Software went this way. When you do a lot of 3D programming, you end up with a LOT of stuff in complex nested parenthetical expressions. x = (x-(y-(z*2))) Parenthesis usually get a space before the opening and after the ending, since you’re trying to isolate the stuff IN the parens from the stuff OUT of them. By adding another space on the inside, you’re basically forcing every open paren to take 3 characters and every close paren to take another 3. That’s a lot of horizontal space to spend, and I don’t see how it improves readability.

I admit I’m straying into really wishy-washy subjective stuff here, but for me I think of parens as little capsules that enclose and isolate their contents. To take an extreme case:

This is dense, and it’s probably hard to follow the parenthesis pairing…

1
num = (x-(y-(z*2)+2)*foo(z));

This makes the grouping a little easier to see…

1
num = (x- (y- (z*2) +2) * foo(z) );

And this is just as visually confusing as the first example, except wider…

1
num = ( x - ( y - ( z * 2 ) + 2 ) * foo ( z ) );

Granted: When you’re nesting stuff three and four levels deep, it might be time to consider breaking the expression up onto multiple lines. Still, I’m using this extreme example to help illustrate what I’m talking about.

So yes, coders will argue about this stuff. Serious people with fancy degrees will sit around and argue – at length – about how they can optimally arrange blank spaces.

To be continued…

A Hundred!20204144 comments. Or one gross, if you'll pardon the expression.


  1. TehShrike says:

    Indent with tabs, align other things with spaces! I like to decide indentation-width per-computer! :-)

    …I can understand arrowing across tabbed indentation might seem weird after so many years, but I think most IDEs let you hit “home” multiple times to switch between the beginning of the line, and the first non-whitespace character. That’s probably the 1337 way to be navigating around the beginning of the line anyway.

    • nmichaels says:

      I like this approach. It really doesn’t matter with a good editor though. At the beginning of the line? Hit tab and the editor should take you to the appropriate column. I get very frustrated with editors that don’t understand that I don’t want to count whitespace characters.

  2. zacaj says:

    I prefer to even put my braces for the if on a separate line:
    if(a)
    {
    stuff
    }
    else
    {
    stuff
    }
    (the stuff would be indented)

    • fscan says:

      Yes, me to .. i don’t like if the “stuff” sticks to the conditional statement, especially if its a bit longer. Also, as another poster pointed out, the scope is defined much more clearly.

      Also, i would write the expression this way:
      num = (x - (y - (z * 2) + 2) * foo(z));

      • Volfram says:

        Working in a Java-based company where we had no *official* style guide except that your co-workers would yell at you if you did something they didn’t like, I would do all of my braces on the next line to write the code, then move them to the same line just before check-in to avoid getting yelled at.

        I much prefer “brace on the next line.” As mentioned, it’s way easier to line up your scope, and it also makes finding those errant missing/extra braces much easier.

        • Loonyyy says:

          Pretty much this. The most common error I’ve always come across as a uni student is missing braces. Seperating all braces from their conditional statments, and then indenting braces has always been the best way to avoid it. It’s not so much about putting less on the screen but to show which things go together. Each indent should have a brace on the second line and the last. With big nesting, you eat through space, but it’s hard to stuff it up.

          The problem gets worse with nested operations, where you can get the scope of multiple things wrong with a couple of missing braces, or worse, misplaced ones.

          It’s especially a problem on a limited time frame (For some reason we have practical tests)-if you write a massive wallocode, you’ll have multiple operations mixed together, and bad things happen. If you have the time to set it out and set up classes and methods, it’s a lot less likely to go wrong.

          • coarsesand says:

            If you’re really having that much of a problem with missing braces, there are all manner of plugins out there that can help. The best ones for this that I’ve found will insert a balanced pair automatically whenever you type an opener, e.g. “{” -> “{}”, and will highlight unbalanced pairs for you so you can tell when something might be missing. This obviously isn’t going to help in your practicals (wat) where you don’t have control of the environment, but the indented brace on its own line is so very, very odd it’s probably not a great habit.

    • Athan says:

      I used to do mostly that, I’d still keep the ‘else’ on the same line as the closing brace for the preceding condition block though. To my eye it was easier to scan down at a certain indentation level for the } and { characters in the same column. Using “} else {” breaks that.

      On the other hand I’ve been warming to the “it’s a big love-in” (they all cuddle up) braces convention of late.

    • Piflik says:

      I can’t stand opening braces having their own line…also no spaces before parenthesis in a function header…my typical methods would look like this:

      public void doSomething() {
      //do something
      }

      Parenthesis actually don’t determine whitespace for me…operators do…I have a blank before and after each (binary) operator…this expression would look like fscan’s

      num = (x – (y – (z * 2) + 2) * foo(z));

      I do like empty lines to separate blocks of code that belongs together, but at the same time I am quite fond of single line expressions, like simple if statements or try/catch…and especially the conditional operator…

    • TSi says:

      I’m sorry but that’s why i find such coding style ugly. Of course, in your example, there isn’t much to show so it feels even worse. In a real project however, vertical spacing is just so important to me that I even have my second screen (lg w220p) flipped just to show as much code as possible without having to scroll.

    • Steev says:

      I’ve always done the same. I find that the most difficult part of reading code for me is tracing which blocks go together. And the indenting of the code isn’t always enough–especially with long lines of code and 80-character wide terminals/printouts. So braces ALWAYS go on their own line for me, to make it far easier to match top to bottom.

      I’m curious, though–do braces get the indent of the contained block, or the conditional statement? Mine don’t get the indent, but I’ve seen both ways, and never really had a major preference.

    • wererogue says:

      I’m used to keeping conditional statements on a separate line from scope specifiers – i.e. I do this:

      if ( condition )
      {
        //response
      }
      else
      {
        //other response
      }
      

      It’s from an ease of debugging point of view. With a few keystrokes I can comment a line, and turning off an if or an else with a comment is very convenient.

      //if ( condition ) //You can't do this with the brace here
      {
        //Respond anyway!
      }
      

      The else part is just a sad byproduct.
      In fact, I’ll sometimes write self-contained chunks of code in a scope anyway, just waiting for a potential condition:

      // I could put an 'if' here!
      {
        //Some data transform
      }
      
      • MichaelG says:

        I do this too, and it makes it easier to copy blocks around when you restructure the code. Having the else attached to the start of the block is a nuisance.

        Also, I learned C right after learning Pascal, which uses “begin” and “end” keywords, not braces. Sticking those with your if and else keywords really looks ugly.

        • krellen says:

          Oh, right! That’s why I’m a “bracket on its own line” guy.

          It’s been so long since I did real programming, I forgot.

          • Rick says:

            I started with Pascal with begin and end, and I hate having starting braces on a new line.

            I doubted that having headless braces would work in PHP (my main language) but it does. Very useful though I don’t know if I can undo so many years of engrained habit.

        • Deadfast says:

          It also makes the code much easier to traverse if you can clearly see where each block begins and ends.

        • TMTVL says:

          I’m the worst coder ever, I go:

          if (shamus.length > 1000) {
          .return “Wow, you’re huge”;
          }
          else {
          .return “You’re not so big”;
          }

          Edit: According to Wikipedia, the “Compact control readability style”.

          • Felblood says:

            This is actually what I usually do.

            Though I will TEMPORARILY move the brace down, after the “else”, when I count up the brace pairs at the end of the function, which you should always do before moving on to another thought. It’s so much faster to check this *now* when you can still remember how it *should* look, than later, that it is a worthwhile habit, even if you waste several minutes a day, every day.

            That line in Shamus’ example:

            “}else{”

            makes me want to chew glass.

            I can understand wanting to eschew

            }
            else
            {

            –but that’s just going too far.

    • Rick says:

      What’s your logic/reasoning for putting the opening brace on a new line?

      I’ve seen many projects/programmers use this style but it has never made sense to me and nobody has explained the appeal behind it. Don’t get me wrong, I almost always put the following code on a new line and indented with the exception of statements such as

      if ($foo) { return false; }
      or
      if ($bar) { continue; }

      otherwise it’s

      if ($foo) {
      //code here
      }

      • Alexander The 1st says:

        The main reason, as far as I can tell, is that putting it on a new line indented to the statement that comes before it is so that you can easily tell where to expect a brace if you’re missing one – you know at what indentation it *should* be on.

        Personally, I still dislike it, though maybe that’s partially because I started with Python (Which enforces colons on the same line, IIRC), and also because most IDEs will tell you which brace is pointing to which brace.

    • noahpocalypse says:

      Yeeeeeeeees…..

    • mystran says:

      I actually used to put the { on the same line and } else { on one line and so on for a long time. I even used to put { after function names.

      I switched largely because of how (stupidly) MSVC auto-formats code. It turns out that if you need to split a branch condition to multiple lines, in MSVC the only way it’s going to get auto-formatted is “if (….\n\t…)” where \t stands for “one level of indent more than where the ‘if’ was indented” and unfortunately if you put { on the last line.. it means the conditional block will get this exact same indent.

      You could argue that such long branch conditions are “bad taste” but long function prototypes, C++ iterator loops, etc all lead to “wider than 80 characters” pretty fast. Since I like to regularly do “reformat whole file” (which in MSVC is C-a,C-k,C-f), my coding convention is generally constrained by “how can I get the pretties code from the auto-formatter”. If I was still using a more intelligent editor (used to use Vim) then I’d probably still use a more compact convention.

      So why auto-reindent? Well, if you make sure your code always auto-indents right, then doing a full reindent is a really quick way to check that all the blocks are like they should be. It’s also very helpful when refractoring, cut-pasting large blocks of code around… and as far as source control goes.. every half-decent VCS knows how to ignore white-space anyway. ;)

      Regarding the function parameter parenthesis.. from reading id’s published source code (eg Quakes), I’d bet they really mean to put spaces on parenthesis WHEN those are function call parenthesis (instead of just grouping). If you think about it that way, it actually makes sense: you can tell which parens are grouping and which ones are function call (in case you ever end up with an editor without parenthesis matching highlight).

  3. aldowyn says:

    Hmm. I need to rethink how I organize my code. I’ve only taken a couple of high school java courses and am in a second college programming course, but I’ve already gained a few bad habits, especially in regards to braces.

    I’ve always visually separated my blocks using the braces, but that’s not the best way to do that – indentation is. (whether with spaces or tabs – tabs is easier for my lazy self, although I don’t yet have a strong opinion on the subject) You should be able to look at a program and just TELL where the different levels of the code are pretty easily without the braces, and as such they do not deserve their own line, since they’re more useful to the computer than to the user.

    The advantage of putting them on their own line or at the beginning of a line is in pairing them, but a decent compiler/IDE or whatever will tell you if you have too many or not enough and from that point it’s not as hard to check, especially if you’re consistent. Like you’ve said, consistency in programming style almost always trumps whether it’s actually BETTER.

  4. Mr. Son says:

    *looks at his own code sheepishly*

    if (a < b)
        {
        biggest = b;
        }
    else
        {
        biggest = a;
        }

    Er… It’s a private project and the important thing is that it’s readable to me?

    • aldowyn says:

      … Man, maybe it’s just me but why ‘biggest’ instead of ‘max’? (I think variable names might be the part where my coding style is technically the best)

      My braces might be worse than yours, though !

      • Brandon says:

        For what that code is doing, I don’t think max is a great descriptor myself. Max is okay for things like end conditions for loops, or other “end” indicators, but the example he gave looks more like a sorting condition. Biggest seems to suit it better. Just my opinion of course. :)

        • aldowyn says:

          well, ‘max’ and ‘biggest’ essentially mean the same thing. They’re both absolutes that imply more than 2 (otherwise you could use ‘bigger’).

          Not to mention I’m used to doing that exact check in a loop checking for a min/max value from a list/array.

      • Mr. Son says:

        I didn’t really pay much attention to the variable names. I was just copy/pasting what Shamus wrote, then moving the braces to show how I placed them. Variables are a whole ‘nother story, and I’d have to actually go look at my code to remember what I’ve been using.

      • Alexander The 1st says:

        Well it could also be force of habit.

        For example, max is a built-in function in Python, IIRC.

        It also could refer to MaxMSP, the visual programming language.

    • Canthros says:

      Wow. Whitesmiths. I’ve never run into anybody that actually used that.

      … As an advocate of the One, True Brace Style, I think I’m required to hate you with a passion that burns with the fire of a thousand suns. (Seriously, though, ew. Whatever works for you, man, but I couldn’t stand to read code that way. :) )

      • Mr. Son says:

        There’s a name for it? Oh, wonderful!

        None of the guides I was following actually used it. They had the opening braces up with the if and else statements, and I just moved them down because it was easier for me with the braces paired up visually on the same vertical line.

        ETA: It’s possibly because I’m a spacial thinker, and tend to need my visual environment arranged Just So, with all the elements aligning “properly” with each other as my brain dictates.

      • Ish says:

        I’ve always used the GNU style and while I’ve seen plenty of code in other formats, It’s always made my brain hurt

        • nmichaels says:

          Wow, I thought only RMS used GNU style.

        • Canthros says:

          The GNU style is also an abomination unto Nuggan.

          But, hey, whatever works for you. I don’t even really use the K&R/1TBS; it’s just the closest approximation. Windows tends to favor Allman-style braces (yet another abomination unto Nuggan), which I find preferable to GNU or Whitesmiths, but still unnecessarily drawn out. I once likened it to “inserting dramatic pauses into a reading of a grocery list” (cf. a bad impression of William.

          Shatner as Captain! Kirk.)

    • wheals says:

      biggest = ( (a > b ) ? a : b);

      Sorry, couldn’t resist ;p

      (You could make a good case that your way is much easier to understand at first glance, but I think for something this simple I would usually prefer the ternary operator.)

      • fscan says:

        biggest = std::max(a,b);

        fixed :)

      • psivamp says:

        I personally hate the ternary operator. I always forget if it’s (condition)?true:false; or (condition)?false:true;.

        So, for me, the ternary operator isn’t worth it because I have to google it every time to remember the order — too much work for ‘future me’ if the project lives.

        • Julian says:

          I find it easy to think of as a compressed if-then-else.

          I also don’t use it very often, because it’s not the easiest thing in the world to read.

          • psivamp says:

            You know, that helps. For whatever idiot reason, I never noticed or connected that it’s in the same order as any if-else statement. Still, I don’t like it and will probably never use it, just in case future me forgets again.

        • wererogue says:

          I have learned to love the conditional operator, because a few key compilers love it too, and will do a conditional move operation instead of a branch. Compilers are getting better at doing the same thing for actual ‘if’ statements now, but it doesn’t hurt to help them out a bit.

        • nmichaels says:

          Python’s ternary operator is spelled:

          expression if condition else expression

          where “if” and “else” are keywords. I think it does it very well. It’s also a good way to think of C’s. ? = “if” and : = “else”.

        • Canthros says:

          The ternary operator is fine if the resulting expression is simple, clean, fits nicely on a single line, and doesn’t need to be repeated. Such an instance should be infrequent.

          In practice, this is not usually the case, and I’ve seen expressions with the ternary operator that ran for more than a hundred characters, were copied and pasted across dozens of lines, contained functions called on the results of functions called on the results of other functions …

          As near as I can tell, part of the problem is the novice discovers the ternary operator, and quickly goes looking for problems to solve with it, with it soon spread all over the codebase.

          It’s probably better not used at all than used badly. But, it’s best used sparingly. It should be part of your tool kit. A small part.

    • Raygereio says:

      If it’s any comfort: I use the exact same style.

    • Simon Buchan says:

      If it’s any comfort, Dinkumware’s implementation of STL (shipped with Microsoft C++ with some modifications) uses that style, or close. Just ignore all the deliberate _Uglyified_identifiers – they’re there to avoid macro clashes.

  5. bloodsquirrel says:

    OBJECTION!
    Edit: For some reason, the comment thing is eating my spaces :/

    I write my else statements like this:

    . if (whatevs) {
    . stuff;
    . }
    . else {
    . otherStuff;
    . }

    The problem I have with putting the else on the same line as the if’s closing bracket is that it gives a false sense of scope; lines of code that are indented the same are generally in the same scope. The ‘else’ here should be indented the same as the ‘if’ because they’re part of the same block of code that is being processed sequentially.

    • aldowyn says:

      If you put the else after the closing brace the line IS indented the same, it’s just not the if and else that are aligned, it’s the if and the closing bracket. A little irritating, but technically true. I have a habit of aligning braces, though, which really wastes space.

    • Ace Calhoon says:

      I also do my if/else blocks this way. I like how it makes the structure of each block consistent:

      [statement] {

      }

      It makes it a bit easier to skim the left-hand margin looking for branches.

      Of course, part of this is probably because I work with a lot of languages that have kind of wishy-washy block structure. If I can disregard everything after a closing brace, it helps in cases like this:

      $(foo).each(function() {
      ….//Do stuff
      });

    • Wedge says:

      Yeah, this is how I do if/else as well. I don’t think anyone would write code that looks like Shamus’ second example–if they’re putting the else block’s open bracket on its own line, they’re going to put the if statement’s bracket on its own line as well; whether people put opening brackets at the end of the statement or on its own line is a separate issue from the if/else thing.

      But yeah, the } else { bothers me, because I expect the if and else to line up visually.

  6. Chris says:

    I have always used 2 spaced indents and avoided a tab, even though if you use tab ( you can change your tab for 2 and another developer for 4 and the ide will take care of it for you so a little more flexible developer to developer if everybody is on same page, rarely the case in large enough organization ). Few years ago, another developer altered my 2 spaced indents by changing every line making it difficult after a bug was discovered to find what line had changed because all lines were identified as changed in source safe. A pain in a large program when 2000+ lines of code all come up as changed to find one stupid bug. After that we decided what the teams standard was and checked all code out, modified it to the standard, and checked back in.

  7. Brandon says:

    One thing that drove me crazy about using Microsoft Visual Studio (At least the Web Designer) is that the default formatting for if then elses forced all of the curly-braces onto their own lines. I like having the open brace at the end of the same line that has the if

    if (x) {
    // Do stuff
    } else {
    // Do different stuff
    }

    but the default format for the C# in Visual Web Designer was

    if (x)
    {
    // Do Stuff
    }
    else
    {
    // Do Stuff
    }

    It drove me crazy.

    Also, a little note on the last part you wrote Shamus. From the wording (and the example given in the document) I’m not sure they intended for all parens to be padded, only the ones encapsulating arithmentic expressions. So it would clean it up a little at least to remove the padding around the function parameter list.

    num = ( x -( y – ( z * 2 ) + 2 ) * foo(z) );

    It looks a little better I guess, but unless I was being paid by the keystroke, my ideal would be more like this:

    num = (x -(y – (z * 2) + 2) * foo(z));

    Oh, fun with coding standards. Earlier this year I worked at a small company that was building some fairly big systems with only one programmer (until they hired me, I was programmer #2). One of the biggest problems I kept running into was that we were working with some legacy code left by a programmer who came before both of us, and his variable (and database entry!) names were rife with spelling errors and inconsistencies. He had some tables where every field was named something like txtFirstName or chkIsMarried, and then other tables where the field was just called “married”, and it was a string field, but a checkbox input on the form. Brutal stuff.

    • Deadfast says:

      Have you ever tried to do a bracketed switch? For some reason Visual Studio insists on doubling the indentation…

      switch (stuff)
      {
      ____case 0:
      ________{
      ____________//The hell?
      ____________break;
      ________}
      ____case 1:
      ________{
      ____________//Somebody stop this!
      ____________break;
      ________}
      ____default:
      ________{
      ____________//Sigh…
      ________}
      }

      • Kdansky says:

        The best solution to ugly formatting with switch-statements is to not use them. They very often result in bugs when you forget the “break;”, they are not significantly faster after optimising, and they only work for very few types in most languages. Of course, Scala or C# have more powerful switch statements, but they also don’t bother so much with the pointless brackets to begin with.

        • Brandon says:

          I’ll be honest, I don’t think I’ve ever seen a switch with brackets in it.. seems unnecessary. I always see them as

          switch(x){
          case 0:
          ….
          break;
          case 1:
          ….
          break;
          default:
          ….
          break;
          }

          • Shamus says:

            You need brackets if you’re going to declare variables inside of a case. On the compilers I’ve used, declaring a variable right after a case will generate and error or warning the it’s skipped by the switch statement, unless you enclose it.

  8. Hitchmeister says:

    My programming was mostly limited to BASIC on a TI 99/4a with a theoretical 16KB of memory. Theoretical because we learned as we approached that limit that there was about 2KB used up by the system and unavailable for user programs. As our programs got semi-complicated we found ourselves having to eliminate every space, carriage return and meaningful character in variable names to get them to fit in the memory available. Readability was a luxury we could not afford. But then again, I was just a kid messing around.

  9. silver Harloe says:

    You can tell your source code control software to run command line programs on files before checking them in – a leading space regularizing app can prevent those nasty “he reformatted the whole program” checkins

  10. burningdragoon says:

    I usually, except when I don’t, have the too much whitespace way of:


    if(condition)
    {
    // stuff
    }
    else
    {
    // stuff
    }

    Though it’s more liking the braces being aligned with each other than anything else.

    • I was going to say this, but you beat me to it. I like my code to be seen and read in easily-understood blocks, and I like to be able to determine which block a particular line is in by how deeply indented the line is, and which braces are supposed to match each other based on the same. This has the biggest impact when doing something that changes indentation levels; it’s easy to see based on indentation where the missing or extra brace is. If the brace is on the same line as the else, it’s harder to find.

      I have no objection to placing a single statement on the same line as the else, but if it’s a block it should start a new line for the brace.

      I recognize this has information density implications when displaying. I find that it helps justify the purchase of multiple large, high-resolution displays for use while writing code…

  11. Kian says:

    Shamus, with the parens example at the end you cheated a little. The coding convetion calls for spaces before and after the parenthesis, but you also spaced operators!

    num = ( x - ( y - ( z * 2 ) + 2 ) * foo ( z ) );

    should instead look like

    num = ( x- ( y- ( z*2 ) +2 ) *foo ( z ) );

    Personally, I like the space before and after, as I don’t just want to isolate the code inside but draw attention to the fact that I am putting a paren there. Of course, too much whitespace can result in trying to draw attention to everything, which much like bolding everything in regular text, results in not drawing attention to anything.

    • Shamus says:

      I wasn’t trying to cheat. The operator spacing was given in the id guide. Although the guide didn’t explicitly SAY operators HAD to be spaced, I sort of took it as a given.

      I was trying to show how spaces (or lack thereof) is more useful for visual grouping than “always put spaces around this thing”.

      • Kian says:

        What I meant was, if you’re talking about how whitespace affects parenthesis, then an apples to apples comparison should be used. If you’re going to bring up how the different rules interact, that would deserve a heading of it’s own.

        You can separate parenthesis by either applying whitespace to operators or to the parens themselves, and get different effects depending on how much whitespace you use. Using both rules will result in too much whitespace, as you show, but that’s a different argument.

        • And this is exactly why there is a standard. We could go on for hours, not arguing about the question, but just discussing how the question should be phrased.
          Good gravy, it’s amazing anything ever gets done.

          • Kian says:

            If I wanted to be productive, I wouldn’t be browsing the web ;)

            • Bryan says:

              …Or arguing about coding style, for that matter. :-P

              Not that I should talk. I’m sitting here disagreeing with most people in the comments on this post for one reason or another (…at least nobody has started talking about the GNU brace style, where braces are on separate lines, and indented *half* a level, while the code in each block is indented a full level), just trying not to say anything. :-)

  12. Blue_Painted says:

    I’ve got to go for

    if(condition) {
    // code – indented!
    } else {
    // other code
    }

    .. with NO white space around parentheses.

    And, just to be picky, cinderblocks are quite light … maybe a paving slab?

    • Cuthalion says:

      This is how I do it as well. I used to do {} on their own lines, but I’ve since switched to this. But no padding of parentheses after an if or a function/method name.

  13. TehShrike says:

    OH LOOK, A LOT OF THE PEOPLE WHO FOLLOW SHAMUS’ BLOG ARE PROGRAMMERS, WEIRD!

    • Canthros says:
      var readerCount = Shamus.Blog.Readers.Count;
      var proggerCount = Shamus.Blog.Readers.FindAll(x => x is IProgrammer).Count;
      if ((proggerCount/readerCount) > 0.25) {
          // NOTE: not actually all that weird
          var msg = String.Format(CultureInfo.CurrentCulture,
              "Oh look, a lot of the people who follow {0}'s blog are programmers, weird!",
              Shamus.FirstName);
          Console.WriteLine(msg.ToUpper(CultureInfo.CurrentCulture));
      } else {
          // blah, blah, blah
      • Augh! Magic numbers! You put that 0.25 in a proper global variable mister!
        Or here, use this:
        #define 0.25 0.618

        • Canthros says:

          I’m working in C# (which means I omitted a *lot* of unnecessary “object-oriented” boilerplate). #define doesn’t work that way in C#.

          (Also, globals are evil, what is wrong with you.)

          I don’t like to create constants to hold magic numbers unless they’re used in multiple places. A constant that will be used once is a waste of time unless its meaning is obscure without hiding its value behind a descriptive variable name. Since this is (obviously) 25%–wait. Why am I justifying code style in a throwaway gag to somebody I’ve never met, on the Internet?

  14. Nick-B says:

    Sometimes, I wish I could do away with braces entirely and just do indent-based enclosures. Such as the shortcut you can do with single line if/else statements, I wish you could do the same for the rest. No more stray squiggly lines, no more forgetting to close a statement somewhere:

    if (a>b)
    –bigger = a;
    –return bigger;
    else
    –bigger = b;
    –return bigger;
    more code;
    more code;

    where “-” is an indent. My preference, of course, is a single tab character, which is 4 spaces wide.

    I have an utter hatred of braces. But since I cannot do without for most cases, I use the “proper” way (lol) of making braces their own line.

    if (a>b)
    {
    –bigger = a;
    –return bigger;
    }
    else
    {
    –bigger = b;
    –return bigger;
    }

    Strange, but I just can’t stand to have a curly brace NOT be on it’s own line. *shrugs*

    • Ithilanor says:

      Isn’t that what Python does, using whitespace to delimit blocks of code?

    • bloodsquirrel says:

      That’s how Python works.

      I’m not crazy about it myself. When you’ve got a lot of different levels of indentation, it can get a little hard to parse without some good ol’ solid {} to look for.

      • Wedge says:

        My advice is “try not to nest things too deep” which is good advice in any language. Personally I find Python’s syntax really nice 99% of the time, and the 1% of the time you need to do something deeply nested it’s going to be a pain to keep track of regardless.

        • Alan says:

          One of the many excellent bits in the Linux CodingStyle:

          Now, some people will claim that having 8-character indentations makes
          the code move too far to the right, and makes it hard to read on a
          80-character terminal screen. The answer to that is that if you need
          more than 3 levels of indentation, you’re screwed anyway, and should fix
          your program.

          In practice, nesting out to 4 or 5 is too convenient in the short term, and I also find it hard to visually interpret in Python, especially for long blocks when you “close” two or more blocks at once.

          • Trithne says:

            I’ve got a Legacy VB6 (!) app at my workplace that’s pretty much the bread and butter of an ongoing project which has a colossal nest of if-thens that gets 7 layers deep at points and goes on for far too long. I leave it mostly alone because I just don’t want to have to unsnarl the bloody thing.

          • Kdansky says:

            The other question is: “Why do you use 80 characters to begin with?” If you can’t afford a bigger screen, you must be a really bad programmer, because that means you have not worked for money in a decade.

            It really annoys me when people start to put their 95 character lines on two lines, just so they fit the outdated 80 char limit. I’m not going to print it!

            • Alan says:

              Lack of emphathy, lack of imagination, and a gratuitous insult, all in one package.

              Some of us like to use our large modern monitors to display multiple columns of code, 2 or 3 wide, maybe even 4 or 5 if you’re a youngun’ with good eyes. When juggling a hairy ball of functionality across multiple files (ah, the joys of legacy code), it’s nice to be able to keep a big chunk of interrelated code on screen at once. It seems silly to have a 16:9/16:10 monitor and have big swaths of the screen be blank except for the occasional long line sticking out looking lost.

              If you’re working with other people with different fonts and font sizes, or even with yourself in the future who may have a larger monitor, there isn’t a single “correct” width. So if you’re picking an arbitrary number, why not 80, which is at least traditional and fits the default width the terminal window (since the context is Linux). I can’t speak for everyone, or even most languages, but my own experience, the experience of my coworkers, and presumably the experience of Linux kernal hackers, is 80 columns is reasonably comfortable for C and C++. Some lines will need wrapping, but it’s unusual enough to not be a bother. And, like any style rule, it should be applied with common sense and occasional exceptions.

              • Kdansky says:

                >Lack of emphathy, lack of imagination, and a gratuitous insult, all in one package.

                I’m efficient!

                There is no need to force everyone to use 80 characters and murder the traitors. Most lines will be shorter than that anyway, or rather, if all your lines are longer than that, then there are bigger problems about. On a 1920×1080 screen (why are we still using those?!) you can easily fit two columns of about 120 characters, which gives everyone 50% more space to work with.

                Just because *you* like to put four columns on a single screen doesn’t mean that I want to scroll through 5000 lines of code, and to make matters worse, if you enforce such a limit harshly, people will start to use shorter variable names (such as “val”), and then readability suffers very badly. Now, you can just get a second and third monitor, while I cannot make your vertical code any shorter, no matter what I do. So in the end, I ask for something that we can all work with, and you ask for everyone else to follow your personal needs. Who is the egoist now?

                Asking people to try to keep their lines somewhat short if possible is fine. Enforcing a strict rule is not.

                • nmichaels says:

                  Enforcing a strict rule makes it so that I can configure my editor to open to exactly the correct width, and I can open 6 columns worth of editor across my 2 monitors without fidgety resizing. There’s also the readability aspect. Long lines are harder to read. Ever notice how newspapers are really wide, but they never use all that horizontal space? Humans aren’t good at tracking across very long lines. Of course there are exceptions, and sometimes you need long lines for your big table initializations. Nobody shoots style guide traitors these days, as long as they have good reasons.

                  But given that there should be a hard limit on columns for normal code, 80 is a pretty good number.

  15. Zukhramm says:

    The example of wasting space on the else statement is really odd, mixing keeping the opening bracket on the same line as if, but not on the same line as else. Is that actually a style in use anywhere?

  16. SteveDJ says:

    I like braces to follow what is done for the actual function itself. So, if I’ve got:

    void MyFunction()
    {
    // do stuff
    }

    …then I’m going to do the same with every block inside the function (that is, put braces on separate lines).

    Above, someone suggested they like to indent their braces — that only looks good if you indent the braces for your function as well. Otherwise when you get to the end of your function, you will have a gap in closing braces that looks like you missed closing a block. That is:

    void MyFunction()
    {
    ….if (something)
    ……..{
    ……..if (something else)
    …………{
    …………//do something
    …………}
    ……..}
    // this line looks like it should have a brace
    // with this kind of brace-indenting.
    }

  17. Anachronist says:

    I’m not advocating this, but I’ve seen the following rather odd style of saving vertical space:

    if (condition) {
        for (i = 0; i < n; ++i) {
            /* do something here */
            if (some_result_condition) {
                /* do something else */
    }   }   }
    

    I’m all for saving vertical space, but that style of closing nested blocks in a single line just looks weird.

    • AyeGill says:

      Maybe the people who wrote that were lisp programmers? In lisp, the idiomatic style is to have all your closing parentheses on one line.

      • Anachronist says:

        But LISP, as far as I know, doesn’t have a style illustrated above in which the order of the braces is inverted from the nesting position. The brace that’s indented to look like it closes the outer block syntactically closes the innermost block.

        • Asimech says:

          With Lisp people usually do what Piflik mentions below. What you’re showing has the advantage that if you’re unsure if you have the correct amount of parentheses, and the editor doesn’t highlight the respective ones, you can just do a vertical comparison if any has been missed.

          That is, instead of counting them all. And since Lisp has the opening parentheses before the function/whatever they’re easy to spot for comparison.

          Of course Common Lisp is a bit different from most other languages in that it’s normal to get huge piles of closing parentheses even in small programs. So it makes sense to try to shove them all in a single line. I wouldn’t do it in C or C-like languages though.

    • Piflik says:

      You should be glad whoever did this at least had tabs between the closing braces…I once saw something like this:

      if (condition) {
      for (i = 0; i < n; ++i) {
      /* do something here */
      if (some_result_condition) {
      /* do something else */
      }}}

      • Anachronist says:

        That actually makes more sense because it doesn’t confuse indentation position with brace order; it’s more like nested parentheses in a mathematical expression. Throwing in tab positioning introduces weirdness because the visual position of the brace doesn’t correspond with the block that the brace actually closes.

  18. neothoron says:

    Without any question for me, the very worst indentation policy I know of is Java‘s:

    * Indent once? 4 spaces.
    * Indent twice? 8 spaces or a tab that must be set to 8 spaces!

    Otherwise, about the style of putting else take 3 lines, I worked in a company (of 4) where that was the policy, because about half of the team said they could not easily read the style where else takes 1 line (and as it was a very new company, screen space was already a non-issue).

    I do not think that tabs are superior – that is, tabs have the advantage of making indentation flexible for the reader at the cost of the author’s intended indent, which is fine for “regular” indentation, but falls apart in more complex cases. You already mentioned non-leading formatting; I will take the example of a function definition that must otherwise be line-wrapped:

        void longName(int par1, int par2
                      int par3, int par4);

    Here, you see that by using spaces, I can use my preferred style for long function parameter lists, which I think reads pretty naturally. You can achieve the same effect with tabs, but it means that you have to mix tabs and spaces (and in the right proportion) in order to achieve the same indentation reliably. You can get similar problems e.g. with long array initializers in C++.

    • daemon23 says:

      Ugh, I just told my story about a C dev who did this exact thing. I’ve been working in Java for years, and I’ve never even known they had this as a convention, nor worked anywhere it was actually used.

      • neothoron says:

        This convention was used at Sun, I saw it only when stepping into the JRE’s source code. As I did not have my tabs set to 8 spaces, it was always extremely painful to read.

        It also looks like that recent releases of Java source code have cleaned that up to adopt an “all spaces” approach.

  19. WWWebb says:

    Yay, VBScript! No worrying about brackets.

    It’s like Shamus is doing a whole series on reasons it’s nice to not be a “real” programmer…

  20. silver Harloe says:

    I “mostly agree” with the id doc, though I strongly disagree on leading tabs – the “ability to change tabstop” can only lead to pain when there are mixed tabs and spaces (see neothoron’s example above about long argument lists)

    whitespace around operators, ESPECIALLY the ! operator, which has a great habit of hiding when right next to other tokens. Comma operator is an exception: space after, but not before

    space inside parens – all of them, except when nested and clarity can be improved by tightening groups (though I’d rather recode)

    space after language operators like if, while and do, but not after function names (the idea being to make it clearer that it’s a function)

    coddled elses, of course.

    one thing I’d add is: handle exceptions early and return, rather than indenting your function 500 columns

    since I don’t do C++, several of the other conventions are meaningless to me.

    function foo( arg1, arg2 ) {
    ….if ( condition1 && ! condition2 ) {
    ……..code
    ……..return;
    ….}
    ….no “else” needed anymore, and thus we save a block level
    }

    bar = foo( arg1, arg2 );

  21. RodeoClown says:

    Shamus, have you read Code Complete (http://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670)?

    It outlines WHY it’s good to use specific whitespace constraints in a team environment. Also, it’s just a great read.

    I like my braces on a separate line so I can easily track the start and end on a block of code, and I put whitespace around EVERYTHING in parentheses.

    I think putting the braces on the same line was so books could publish code and actually have it fit on a page, instead of sprawling over 2 or 3 pages.

    • Alan says:

      You only have so much screen. Modern screens are big, but once you have space for your compiler output/run output, and a few editor windows open for the several related pieces of code for your current problem, each individual code window isn’t that big, and the more code you can cram in there, the more you can quickly scan. That’s why I err toward the more dense end.

      • Deadfast says:

        Yes, modern screens are big, sadly they’re big on the wrong axis. I absolutely despise 16:9 screens.

        • Bryan says:

          I have no idea what I’ll do when this 1280×1024 17-inch LCD dies. :-(

          I’d probably look for a 1600×1200 replacement, but those were super-expensive as well last time I tried to find one, plus I don’t know if this desk has room for it since they’re quite a bit wider and there are shelves to the left and right of the current LCD.

          But 5:4 is reasonable, and 4:3 is best. 8:5 (or “16:10″ for people who can’t divide) and 16:9 are just annoying. I’ve got a great idea; let’s destroy a bunch of rows of pixels, to make the aspect ratio match theater screens, when that matching isn’t even required (since, first, not all DVDs are “widescreen”, and second, I watch them in a window anyway since I’m usually doing something else too).

          Also, get off my lawn. :-P

          • Bubble181 says:

            16:9 (16:10 is completely ridiculous) screen ratio has nothing to do with cinema (which is even flatter at 2,39/1), and more with ergonomics.

            It may be less “common” and it is, of course, annoying for some things (if you read a LOT of A4/letter paperwork on screen it may be easier to flip your screen around), but it fits our field of view (16/9 is 1.78, our field of view is about 1.75).

            For anyone using any application full screen, or in other ways using their whole screen, 16/9 is far easier on the eyes and neck than 4/3.

            Coding convention – and our mind’s problems with parsing – come from coding on long thin strips of paper, and reading long lists. Homo Sapiens worked in 3D, Sapiens Sapiens works almost exclusively in 2D (we get confused when we have to do hard 3D stuff), and more and more you see people using one dimension to the near-exclusion of the other one, even at that.

            Strictly speaking, a child reared to do it that way would be better at parsing text using both dimensions to the fullest, than one who’s used to “our” way would be at parsing “our” code.

            Anyway, I can nag, but for my work I use 5 displays: 4x 4/3 next ot each other, and a 16/9 on top of the two central screens….

            • Shamus says:

              I actually have a 16:10 monitor. (1920 x 1200 native.) I gather it’s sort of exotic, and 16:9 is considered the standard now. I had no idea when I bought it. Now it’s a bit annoying because some software is a bit dumb about adjusting to it. Games never pick my native mode, but usually detect that it’s NOT 16:9 and so assume 4:3. This ends up with many games starting up in some screwy mode where everything is boxed in, stretched, and off-center.

  22. ngthagg says:

    RE Braces: I use a separate line for both the opening and closing. For the opening brace, at some point I developed a distaste for shortcuts in coding, and began to prefer visual clarity. I like my code blocks to be distinct from the code around them.

    As for the closing brace, I don’t mind seeing } else lines, but the else will disappear when I collapse the preceding block so it isn’t an option.

    Indeed, I find any discussion on braces and code blocks to be incomplete without consideration for the role collapsing plays in reading and writing code.

  23. StashAugustine says:

    #define CONSTANT

    int main()
    {
    int MainVar;
    MainVar= input_function();
    if (MainVar>= 3)
    {
    MainVar= MainVar+ CONSTANT;
    }
    else
    {
    MainVar= MainVar- CONSTANT;
    }
    return 0;
    }

    int input_function()
    {
    int ReturnValue;
    scanf(“%i”,ReturnValue);
    return ReturnValue;
    }

    How is this from a readablity perspective? I’m new to most of the stuff where other people actually have to read the code.

    • daemon23 says:

      Not good. Lack of indentation led me to assume that was a single function in there until I read all the way through it. The problem with not indenting is less obvious for smaller blocks of code than more complex.

    • Bryan says:

      Two bugs I can see. The first:

      #define CONSTANT

      …needs to have a value, otherwise when it’s used later:

      MainVar= MainVar+ CONSTANT;

      the preprocessor will turn this into:

      MainVar= MainVar+ ;

      and the compiler will barf. If this gets fixed, then you’ll get a warning from gcc, and a crash when the program runs, from:

      scanf(“%i”,ReturnValue);

      because scanf needs a pointer to the variable it’s going to read into. ReturnValue can cast to a pointer (in C) since it’s an int, but it has a random value, so you’ll be overwriting a random address based on what scanf parses out of stdin. Should be:

      scanf(“%i”, &ReturnValue);

      (modulo whitespace).

      Sorry, nitpickery done. The formatting is … eh, whatever, it’s not worth discussing all that much I don’t think. :-)

  24. Tse says:

    Wow, I thought I understood the post, but I can’t understand a lot of what’s in the comments.

  25. daemon23 says:

    So, at my previous jobs, one of the developers who had been there longest had the worst indent style ever. See, vim offers, for no sane reason I can think of, a mixed space-and-tab indentation feature. The senior dev used that, and had every tab keypress insert four spaces, and a tab character used every eight.

    For the non-developers, this means that, for anyone with what is often the default, where every tab character is four spaces, when he would write:
    ….if (foo == 0) {
    ……..while (bar) {
    …………/* something something */
    ……..}
    ….}

    It would appear to others as:
    ….if (foo == 0) {
    ….while (bar) {
    ……../* something something */
    ….}
    ….}

    That’s assuming he actually tabbed things consistently, which he frequently did not, so code like:
    ….if (foo == 0) {
    ………..while (bar) {
    …./* something something */
    ….}
    …………}

    …was equally likely.

    Thankfully my primary job was java, and I did not have to touch his code often.

  26. About else statements: They need to be separated from the close-brace of the if so I can see them; but they must have their own open-brace on the same line as the else, so as not to take up three lines. Why is this obvious and completely correct option not considered in your post? Two lines is the perfect solution; all else is heresy! You set up a false dichotomy between the unreadable one-line and the space-wasting three-line extremes. Clearly the only fair solution is to split the difference and use two!

    Anyway. That’s the way I like to write them. It’s consistent in that it treats the else and the if the same way, giving both a separate line with an open-brace. It also treats their respective close-braces the same, both on a single line. If I’m scanning a block of code, that single brace jumps out at the eye.

  27. Shamus says:

    Testing:

    if (a < = b) {
        a = a + 2;
        if (b < a) {
          b++;
          a = 0;
        }
    }
  28. Leonardo Herrera says:

    This post is so close to my heart. And my sanity.

  29. Testing with Supercache in place.

  30. Neko says:

    Ah, joy.

    I too picked up the coding conventions I use today from the last major project I worked on. It was basically K&R style – braces on their own line for namespaces, classes, and methods, trailing braces for control flow constructs. Omitting the braces was strongly discouraged, though, so I guess (after reading the Wikipedia entry) it was closer to the so called “One True Brace Style”?

    Before that I did a lot of Java, so naturally gravitated to the Allman style. But I think K&R is better now, it’s a decent balance of whitespace where it matters – the “big stuff” – with more compact lines for the body.

    As for tabs… I’m a bit strange and use tab characters that indent 3 spaces. 2 is too little, 4 is too many.

  31. Mersadeon says:

    So, when I started reading your blog, I was a non-coder. You kinda got me into it. Now, I am suddenly studying something with computer science in it, typing in code as homework… Well, right now we are learning Haskell, were the formatting isn’t quite as important, seeing as most programs we have to do are two dozen lines at most.

    I just wanted to say, Shamus, you really explain programmer-stuff well to non-programmers.

  32. Suraj Barkale says:

    No style guild is going to be perfect for everybody. I have found Google C++ style guide to be a reasonable compromise. With comments to explain how a decision was made. It also offers cpplint program to check for correct style!

  33. Veylon says:

    There appears to be this tool called “astyle” that can mangle your code into whatever configuration you find desirable.

    It seems a bit unnecessary to harange one another about whitespace when you can press Ctrl-Shift-U (or whatever) and have everything formatted just the way you like it regardless of what it looked like five seconds ago.

    For that matter, why don’t we have compilers that do this automatically when you load up a file? This whole thing feels like it should be a solved problem from a practical standpoint.

    • Asimech says:

      You mean instead of storing the source code as raw text files use some sort of markup language similar to XML that tells the IDE how things are supposed to be organised?

      Sounds more trouble than it’s worth, assuming it would end up being useful.

      Or do you mean have the IDE, on-the-fly, interpret the whole code and show it in different formatting exactly the way the programmer wants it?

      Sounds like it would put too much strain on the hardware to make it practical. If the re-formatting happens when the file is opened it would likely take quite some time. And this is assuming the re-formatting code can actually make sensible decisions, which I find doubtful.

      Or literally changing the formatting when loading the files, thus either causing every single formatted line to be reported as “changed” or complicating the comparison software enough so it can tell when the changes shouldn’t do anything?

      Because that sounds like trouble in the long run. Either you’re a pain on all the other programmers because it takes ages to go through your files for changes or there’s a very real risk the code doing the comparison deciding a change doesn’t do anything when it does and also caused a bug.

      Any comments from programming gurus would help, but I think this problem is like the common cold. Something that feels like it should have been solved long time ago, but is in fact non-trivial to solve.

    • Alan says:

      There are two big problems with just using a tool to automatically reformat code to match your preferences:

      1. Your preferences aren’t easily expressed with a tool. Real world code is complex and tends to have the occasional case where deviating from your preferred style is clearer than strict adherance. A tool can’t tell this and will merrily clobber the well formatted code. You might add additional markup to indicate “This is clever, don’t change,” but now you’ve added an additional detail to remember.

      2. You absolutely need to ensure that code is in some sort of “canonical” format before adding it to a revision control system. If you don’t, you’ll make a commit that looks like it changed every line of your file, which makes tracking down changes very hard. Some revision control systems can do the formatting automatically, or at least can refuse commits not in the canonical form, but not all can. In particular, modern distributed revision control systems like Git tend to require everyone to be configured correctly to get that sort of behavior, and it’s easy to make a mistake.

      The reality is that style is nowhere near as important as programmers make it out to be, we just like arguing about it. I’m sure there are some genuinely terrible style guides out there, but most are Good Enough, and when you join a team you suck it up and adapt.

      • Kdansky says:

        I found there are also huge differences between languages. C++ is impossible to auto-format due to its complex templates, macros and general difficulty in parsing, whereas Java can be auto-formatted (Eclipse comes with a shortcut defined) without any issues. You can also export the settings for the formatter, and put it into the SVN. It’s a great feature.

  34. Mephane says:

    I’d just like to throw into the ring what F# does: it does not have braces nor begin/end. Blocks in conditional clauses or loops are defined by intendation, and F# only cares that a given block uses consistent intendation only inside that block (and only spaces are allowed):


    let someFunction x =
      if x > 0 then
        anotherFunction x
        weirdFunction x
      else
          strangeFunction x
          hilariusFunction x

  35. Steve C says:

    How many characters have been used on this page in order to argue spacing? Oh the irony.

  36. AndyL says:

    I really prefer to have braces on their own line, so that I can see them line up.

    // Easy To Read
    if(MightBeTrue)
    {
    Do Stuff;
    }

    // Harder to Read
    if(MightBeTrue){
    Do Stuff;
    }

    In the second example, it’s not obvious at a glance what that closing brace is connected to. In the second example you have to actually READ the code to understand its structure, which drives me crazy.

    I think else statements deserve to be an exception to this rule, however.

    //This is just as clear as the alternative.
    if(MightBeTrue)
    {
    DoStuff;
    }else{
    DontDoStuff;
    }
    You can still see the structure at a glance, and you don’t waste three lines for nothing.

  37. Alan says:

    *giggles manically*

    So I have looked at quite a bit of HTML code, and I didn’t realise what the blank space was for. On some sites that I worked on there would be so much blank space that it would bloat the pages by quite a lot.

    In these I would do a find and replace, replacing all the double spaces ” ” with one space ” “. In some cases this would reduce the size of the file quite a lot.

  38. Neil Roy says:

    if (a==b) {
       do stuff;
    }
    else {
       do something else;
    }

    I have never liked extra padding around braces, it doesn’t make sense. Doesn’t make it more readable, it just needlessly bloats all your code, stretching your lines out. And like you, I see code in braces as being encapsulated, like a dingle object. I guess it all depends on how you visualize it I s’pose.

    I prefer my if’s and else’s on their own line, I don’t understand the }else{ stuff, it looks just wrong. I find it faster to locate an else when it is on it’s own line, rather than being a part of the initial if() statement.

    Something else that bothers me is needlessly using braces.

    Code like:

    if (a==b) c=1;

    makes more sense than

    if (a==b) {
       c=1;
    }

    …I just don’t see the sense in putting in the braces. If you can’t figure out at a glance that there are no other lines beyond the c=1; part due the lack of braces than you need help. Having a simple bit of code like that just looks cleaner in my opinion.

    In the end, what ever style is the most comfortable for you, stick to it, but do try and stick with one style at least and be consistent.

    P.S: You might want to inform people they can use “& nbsp;” for adding in extra spaces (no space between “&” and “n” though). That is what I did here, I used 3 of them. ;)

Leave a Reply

Comments are moderated and may not be posted immediately. Required fields are marked *

*
*

Thanks for joining the discussion. Be nice, don't post angry, and enjoy yourself. This is supposed to be fun.

You can enclose spoilers in <strike> tags like so:
<strike>Darth Vader is Luke's father!</strike>

You can make things italics like this:
Can you imagine having Darth Vader as your <i>father</i>?

You can make things bold like this:
I'm <b>very</b> glad Darth Vader isn't my father.

You can make links like this:
I'm reading about <a href="http://en.wikipedia.org/wiki/Darth_Vader">Darth Vader</a> on Wikipedia!