Where’s the white space in the code

Writing code is much like writing a book. There is the intrigue, the story, the chapters and paragraphs. It’s all there. But there’s often one thing lacking in code that no self-respecting author of a book would ever do without; Readability.

An author that want people to read his books has to – on top of creating an encapsulating story – make it easy for his readers the read the text. I’m talking about the mechanical reading of the book’s text. So he or she will divide the text into chapters and paragraphs, sometimes even parts and even separate books.

Consider the following:

orem ipsum dolor sit amet consectetur adipiscing elit aliquam consequat urna turpis sociis vivamus varius fringilla justo potenti tellus libero ridiculus commodo est justo sem ante felis velit gravida volutpat molestie inceptos dignissim montes ultrices ridiculus sollicitudin dictumst morbi habitant eu quisque elementum in natoque vel conubia erat consequat elementum conubia at purus morbi commodo cubilia magna semper ultricies nullam habitant tincidunt suscipit aenean ad maecenas hendrerit etiam vehicula cras rutrum interdum blandit inceptos non gravida curabitur donec, nisl et aptent posuere ut nunc vivamus dictumst taciti viverra suspendisse porttitor integer lobortis fames hac facilisis metus tempor congue ridiculus hendrerit sociosqu ultrices faucibus habitasse mattis consequat nibh

The example is almost unreadable, and even though there have been experiments in history where authors have omitted all capitalizations, punctuations, paragraphs and chapters, I think we can all agree that the following exampled is much easier to read than the one above.

Lorem ipsum dolor sit amet consectetur adipiscing elit, aliquam consequat urna turpis sociis vivamus varius fringilla, justo potenti tellus libero ridiculus commodo. Est justo sem ante felis velit gravida volutpat molestie, inceptos dignissim montes ultrices ridiculus sollicitudin dictumst morbi habitant, eu quisque elementum in natoque vel conubia. Hac mollis lectus convallis conubia commodo aptent semper cubilia porta imperdiet, dis enim bibendum nisl eros sollicitudin potenti ad luctus.
Erat consequat elementum conubia at purus morbi commodo cubilia, magna semper ultricies nullam habitant tincidunt suscipit aenean ad, maecenas hendrerit etiam vehicula cras rutrum interdum. Blandit inceptos non gravida curabitur donec, nisl et aptent. Posuere ut nunc vivamus dictumst taciti viverra suspendisse porttitor integer, lobortis fames hac facilisis metus tempor congue ridiculus, hendrerit sociosqu ultrices faucibus habitasse mattis consequat nibh.

Why, then, do I so often encounter code without white space, capitalisations and paragraphs? The below example seems relatively nicely formatted. It is indented, capitalized and with descriptive variable and component names. What it is lacking, is compartmentalizations (or paragraphs) delimited with white space (a blank row) and white space in its arguments.

procedure TAForm.PopulateAList(AList:TList<TItem>);
var
  Item: TItem;
  ListItem: TListItem;
  VAT, TotalPrice: double;
begin
  TheListView.Clear;
  TheListView.BeginUpdate;
  try
    for Item in AList do
    begin
      VAT:=Item.Price*0.25;
      TotalPrice:=Item.Price+VAT;
      ListItem:=TheListView.Add;
      ListItem.Caption:=Item.Title;
      ListItem.SubItems.Add(CurrencyToStr(Item.Price));
      ListItem.SubItems.Add(CurrencyToStr(VAT));
      ListItem.SubItems.Add(CurrencyToStr(TotalPrice));
    end;
  finally
    TheListView.EndUpdate;
  end;
end;

Compare the above example with this one:

procedure TAForm.PopulateAList( AList: TList<TItem> );
var
  Item: TItem;
  ListItem: TListItem;
  VAT, TotalPrice: double;
begin

  TheListView.Clear;

  TheListView.BeginUpdate;
  try

    for Item in AList do
    begin

      VAT := Item.Price * 0.25;
      TotalPrice := Item.Price + VAT;

      ListItem := TheListView.Add;
      ListItem.Caption := Item.Title;
      ListItem.SubItems.Add( CurrencyToStr( Item.Price ) );
      ListItem.SubItems.Add( CurrencyToStr( VAT ) );
      ListItem.SubItems.Add( CurrencyToStr( TotalPrice ) );

    end;

  finally

    TheListView.EndUpdate;

  end;

end;

Yes, it does occupy a few more lines of code, and the code gets a little wider, but isn’t the second example more readable than the condensely formatted code? The initialization where the list view is cleared is its own paragraph making it easy to find all the initialization code.

The try… finally section stands out better and it is clear that the loop consists of two separate paragraphs, the first one calculating some values and the second one doing all the assignments for the added list view item. (Yes, the clean code extremist would probably go further, applying private methods to various part. This is just a simple example to clarify my point).

One of the most common arguments I have heard for condensing the code is that the programmer wants to see as many lines of code as possible at the same time. To me, that is like saying that I’d like to remove all empty lines in the text of a book because I’d like to see as much text as possible at each glance. That’s just counterproductive, it’ll take more time to read the text and you’ll have a worse understanding of it when you’re through.

Code should be written for other programmers. The computer will understand it however you choose to design your code, and you will too. For a couple of weeks at least. You should take care to write code so someone else can understand it in a month, a year or even ten years. The next guy trying to understand your code don’t want a blob of text without beginning, end or middle.

As for being able to see as much code as possible at one time. Programmers that think that’s an issue has gotten it wrong. By using clean coding techniques, well designed programming patterns and a bit of common sense, you can write your code so you don’t have to have 300 lines of code on the screen at the same time.

Consider this last example. The same code as above, but cleanly formatted.

function TAForm.AddItemToListView( AListView: TListView; AItem : TItem );
var
  VAT, TotalPrice: double;
  ListItem: TListItem;
begin

  VAT := Item.Price * 0.25; 
  TotalPrice := Item.Price + VAT; 

  ListItem := AListView.Add;
  ListItem.Caption := Item.Title; 
  ListItem.SubItems.Add( CurrencyToStr( Item.Price ) ); 
  ListItem.SubItems.Add( CurrencyToStr( VAT ) ); 
  ListItem.SubItems.Add( CurrencyToStr( TotalPrice ) );

  Result := ListItem;
end;

procedure TAForm.PopulateAList( AList:TList<TItem> );
var
  Item: TItem;
  ListItem: TListItem;
begin

  TheListView.Clear;

  TheListView.BeginUpdate;
  try

    for Item in AList do
      ListItem := AddItemToListView( TheListView, Item );

  finally

    TheListView.EndUpdate;

  end;

end;

All the specifics of adding and calculating the list item is removed from the loop and handled in a private function, so when addressing a problem with the loop, you can focus and that logic, and when addressing a problem with the calculation of the values, you move to the AddItemListView function and debug that part.

No more need for viewing scores of code lines on a single screen.