Blog

As you might know, I've published a book about C++20 called Programming with C++20. In the course of writing this book, several topics have been raised, which I like to share here with other potential authors.

Where to put the opening curly brace

I was approached at one point about the indention or better formatting I chose. I use clang-format for all my C++ projects, and the book counts as a project as well. That alone is a pretty good thing, I think because, I could quickly reply that the code formatting in the book is consistent and that I can send a clang-format file over which describes the formatting exactly. The second good thing is that within boundaries, changing the format is easy. Adjust the clang-format configuration and write a bash script (single line) that finds all C++ source files and calls clang-format for them. You can find the full clang-format configuration I used for Programming with C++20 here.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

A 
void SameLine() { 
  // ...
}

B 
void NewLine()
{
  // ...
}

There are two basic ideas that putting the opening curly brace in the same line, as in A, comes with:

• Code listings are smaller that saves white space, and with that reduces the overall page-count;
• Code listings are less likely to be broken when spanning across two pages.

A third more emotional argument is what style you as a reader prefer. I did try to get some empirical data by asking a poll on Twitter, "#cplusplus universe where do you like the opening curly brace for a function to be in a example in a book.". You find the poll here.

The final result with 1,266 votes is 49.1% like it to be in the same line (A) and 42% in a new line (B). While this is a result, I interpreted it as there is no real win here. The two choices are too close together for my taste to be conclusive.

I did research some other books about the style there. I checked A tour of C++, and it uses B along with books from Scott Meyers, and Herb Sutter (Exceptional C++). But C++ Coding Standards Herb Sutter wrote together with Andrei Alexandrescu uses A.

Save white space by putting the curly brace in the same line

Let's tackle the initial two statements. We have fewer pages and fewer listings with a page break in the middle. I conducted an experiment for these two, expecting that both statements were true. The version of my book I used at the time had 202 pages in a single PDF with function formatting as in B. It had 174 source files. Maybe not all of them went into the book, but a good amount. I changed the indention from having the brace in a function definition in a new line to having it in the same line as in A. This should reduce the number of pages and the number of listings with a page break. I recompiled the PDF and ended up with exactly 202 pages! Not a single page save with over 100 code examples!

I did a further check. I went through the first three chapters and checked whether there are now fewer breaks in code listings. This was the second reason for putting the opening curly brace in the same line. I found 10 listings that are not broken in the new version anymore. I found 9, which were newly broken, and 21, which are still broken in both versions. I stopped after that (this was after chapter 3 at the time).

Know what you are optimizing

The results above most likely come from the fact that there are not that many function declarations in the book. I can only speculate that with other uses of code listings in a book, the results are different.

This tells me that Donald E. Knuth's statement "premature optimization is the root of all evil" applies to formatting books as well. Further, the rule of software development, measure before you optimize, is true in other areas.

Andreas