15

For instance, non-vertically aligned:

Name:   Hamt
Version:  0.1.0
Cabal-Version:  >= 1.2
License:  BSD3
Author:  Jason Baker

Or vertically aligned:

Name:           Hamt
Version:        0.1.0
Cabal-Version:  >= 1.2
License:        BSD3
Author:         Jason Baker

Which do you prefer and why?

6 Answers 6

19

Personally, I'm of the opinion that the second version of the code is marginally more readable, but I don't think that maintaining it makes up for that readability. Therefore, I'd only use the second version of this example if I was fairly certain that the code wouldn't change.

0
10

Saves time when you just do it like this:

Name: Hamt
Version: 0.1.0
Cabal-Version: >= 1.2
License: BSD3
Author: Jason Baker

Isn't too hard to read either.

2
  • That's actually a properly formatted example, I even have a vim command for that: :%s/\([^ ]\) \+/\1 /g
    – Dorian
    Nov 6, 2016 at 18:30
  • Maybe sort by length? :-)
    – realbart
    Mar 16, 2017 at 16:55
8

I prefer a hybrid:

Name    : Hamt
Version : 0.1.0
Cabal-Version :  >= 1.2
License : BSD3
Author  : Jason Baker

Which is essentially number 2 with exceptions for occasional lines that are longer than the surrounding lines - to prevent the majority of lines being spaced far over.

8

Here is another variation for list layouts based on both experience as well as education from a University course I took on human-computer-interaction and several books I've read on (G)UI design and graphic design. I use it for dialogs, and when I have the energy/time, for CSS (not usually for code though).

          Name : Hamt
       Version : 0.1.0
 Cabal-Version : >= 1.2
       License : BSD3
        Author : Jason Baker

Like all others, it has its pros and cons.

Pros:

  • Strong visual break separates data from labels
  • Aesthetically pleasing, professional graphic-design look (particularly for finalized, published files)
  • Data is closer to label, making it easier to associate (lessens chances of reading across a line to the wrong data)
  • Ideal for dialog box layouts

Cons:

  • Requires more time to format correctly
  • Requires realignment when a new longest item is added
  • Not as useful for code



HTH

3
  • Wow, I've never seen this way. I like it! +1
    – Stephen
    Jan 27, 2011 at 3:07
  • But it is harder to find the starting position of the line and code indention.
    – Sadeq
    Oct 29, 2015 at 11:11
  • what is the name of that style? i prefer it and i am trying to find an atom package that will do it automatically
    – daslicious
    Jul 29, 2016 at 19:27
7

Unfortunately being a style question, this is very subjective and you will likely have many conflicting results. Moreover, the style to use depends heavily on your usage of TABs or spaces.


As for my two cents, I prefer a variation of the second version. I like this best:

Name            : Hamt
Version         : 0.1.0
Cabal-Version   : >= 1.2
License         : BSD3
Author          : Jason Baker

It is the most readable and easy to use version that I have tried. The only real downside is that I have to figure out what the widest field is, and sometimes end up having to expand all of them when one is too wide (this usually only happens with CSS). However there are a few points that need to be considered.

First, I usually prefer TABs as opposed to spaces, however the actual TAB setting varies; for example, I am accustomed to 4-space TABs for C(++) code or HTML and 2-space TABs for Pascal or Assembler code, whereas for some things like CSS, I have no preference for the TAB width. This variation complicates things enough, but then the editor I use throws in its own complications. Some editors let you set per-language TAB settings, but some don't (even some that have different profiles).

You can avoid this complication by forgoing TABs in favor of spaces. Since code is usually in a fixed-width font, using spaces works fine, whereas if you are formatting fields in a form, resumé, or other non-code text and are using a proportional font, you'll need TABs to keep things aligned.

I prefer TABs in general because even with fixed-width code, I find it frustrating to have to cursor through several spaces for each TAB. I recall that the old Borland IDEs had an option to cursor through TABs (specifically entire lengths of whitespace) as a single entity instead of as two, four, etc. spaces. That made it practical to insert TABs as spaces while making cursor navigation easy and fast. Unfortunately I have not seen any modern, Windows editors that can do that.

Finally, whether or not others will be using your code plays a big factor in the choice of style. I am usually the only one who uses my code, so I can format everything according to my taste without regard to the editors or settings of others. If you are working with others, you will need to take them into account as they will need to consider you.


In summary, readability is good and very desirable, however the settings and editors you and others that need to use the code will be important when making the decision. If you are alone, you may as well just use the format that is most readable. You may need to get used to using it, but it will likely pay off in the long run, especially when you need to come back to code you wrote a while back: readability is as important as comments in understanding what the code does. If you work with others, then you will want to work together to set out some sort of design guide for use by the team.

1
  • 2
    "Unfortunately I have not seen any modern, Windows editors that can do that." - Just hold down CTRL when using the arrow keys to navigate inside the text. Almost every editor and text box supports that in windows. It will skip entire blocks of white space, and logical blocks of code in one go. Aug 1, 2012 at 8:16
6

I prefer the first one, but without the tabs (which I guess the blanks are); just one blank space instead. To me that's easier to read when the data is not "similar", as in the given case. It also makes it more difficult (while editing such data) to "misread a row", i.e. when you have three rows with let's say, version numbers. And then while editing one, you accidentally edit another in it's place.

When the data is similar, however, it makes perfect sense to put it in columns as in your second example (only there is it not similar, but you get the point).

1
  • I prefer the first too, also I'm using proportional fonts, so vertical align does not make sense for me.
    – Calmarius
    Sep 9, 2013 at 10:32

Not the answer you're looking for? Browse other questions tagged or ask your own question.