Saturday, August 4, 2012

Another Dimension

Since I keep saying that shorter is better, and at the same time that code needs to be readable, I figured I should dedicate a post to the other dimension of your monitor, which tends to be overlooked when people think about code readability. That's right - an entire (not very long) post about the horizontal placement of your code!

First of all, indentation. It pains me that I feel I have to bring it up at all, but it seems that the subject of indentation is not obvious to all experienced, professional programmers out there.
The common correct way of doing it is adding a tab (2-4 spaces usually) at the beginning of the line every time you enter a new nested block, and a block should be defined as anything that counts as a local scope in C. That is to say, if your if() has only one line after it and no braces, it's still a block and needs to be indented, but switch() cases, on the other hand, aren't blocks, it's just a fancy multiple goto statement inside one big nested block, and there's no reason to waste 2 tabs on it as some people determinedly do.

One thing that can ruin this simple indentation method is C/C++ preprocessor instructions, which, as you know, don't get indented because they're not part of any block per se. Many a function has been butchered by a sudden spike in the indentation, like so:
            if (x>9000) {
                fire (LASER);
#ifdef _DEBUG
                log ("It's over 9000!!!");
That just isn't pretty, and not as easy to read.
Why not do something like this instead?
#ifdef _DEBUG
#define DEBUG_ONLY
#define DEBUG_ONLY //
            if (x>9000) {
                fire (LASER);
                DEBUG_ONLY  log ("It's over 9000!!!");
Better, don't you think?
And if you tend to have _DEBUG blocks longer than one line and don't want to specify DEBUG_ONLY in every line (for some reason), you could still keep the pretty indentation like this:
#define DEBUG_START #ifdef _DEBUG
#define DEBUG_END #endif

Fortunately for this post, there are a few other good uses for your Tab key.
One thing I'm surprised I rarely see is code formatted to look like a table. Whenever you have a series of statements that are very similar in some way, they could become more readable that way. Be it an array initialization, the declaration of data members, or just several lines that do similar things (e.g. the code at the end of this post), making it look like a table helps the reader understand the structure and the similarity between the lines, while at the same time drawing attention to the differences between them. For example:
int m_cVampires;
int m_cZombies;
CWeapon m_weapon;
string m_name;
Just looks less nice than:
int       m_cVampires;
int       m_cZombies
CWeapon   m_weapon
string    m_name;
That's a very simple example, of course. This method would be much more useful in this sort of code:
AddButton (ICON_NEW,         "New File",   "Ctrl+N",   x+=32);
AddButton (ICON_OPEN,        "Open File",  "Ctrl+O",   x+=32);
AddButton (ICON_SAVE,        "Save File",  "Ctrl+S",   x+=32);
AddButton (ICON_PRINT,       "Print",      "Ctrl+P",   x+=48);
AddButton (ICON_BOLDTEXT,    "Bold",       "Ctrl+B",   x+=32);
AddButton (ICON_ITALICTEXT,  "Italic",     "Ctrl+I",   x+=32);
In my opinion, the above piece of code looks much better than it would have without the tabs.

A third use for all that empty space on your fancy wide screen is documentation, and this tends to work well combined with the previous idea; when you have a list of things, and you're keeping the names in your code properly short, you might like to add a few green words next to each item for clarification, for example:
int       m_cVampires;     // number of vampires on the screen
int       m_cZombies       // number of zombies on the screen
CWeapon   m_weapon         // player's current weapon
string    m_name;          // player's name
That saves you a whole lot of space compared to the common method of writing each of those things above the item it describes, and in my personal opinion is also easier on the eyes.

I'm afraid these are all the relevant ideas I have at the moment, but I think that even those could be very helpful. Since wide screens have become the standard, instead of the long screens that would probably be better for anyone who uses their computer to read or write things, we might as figure out a way to use each line to its full potential.

Got any more space-saving ideas? Feel free to comment!

No comments:

Post a Comment