The Case Study

To this point, I have not yet mentioned the subject of the case study central to this book. In my opinion, an ideal problem would be one that is not too daunting and yet not so trivial that it needs no design. Additionally, the domain of the problem should be readily understandable to any reader. For this reason, I have chosen to implement a stack-based, Reverse Polish Notation (RPN) calculator that I named pdCalc, short for practical design calculator. Functionally, pdCalc was inspired by the HP48S calculator, an old favorite calculator of mine from high school and college (which still sits on my desk today). I cannot imagine any reader being unfamiliar with the basic operations of a calculator, and making the calculator use RPN adds a little twist that I hope will make the project interesting. If your sole objective were to code a simple calculator with basic functionality, admittedly, the design of pdCalc is overkill, and more code is written from scratch than is strictly necessary. Remember, pdCalc’s primary purpose is to serve as an instructional tool – a reduced-size representation of a real project. That pdCalc happens to be a functioning RPN calculator is a secondary objective.

Language Selection

Design as an abstract concept can be taught in the absence of a particular programming language. However, once committed to a concrete example, a specific language must be chosen for the implementation. I decided to write the case study exclusively using C++. While every line of the program does not appear in the text, all of the source code is available for the reader to examine. Despite this book’s primary focus on design, reading the source code is a good way to learn how implementation details in a specific language enable or, at least, facilitate a chosen design. The source code also serves as a high-quality (I hope) exemplar of a modern C++ implementation of a complete user application. I highly recommend reading and modifying the source code in conjunction with reading the text.

The decision to use C++ does not imply that C++ is the best choice for all programs, and, in fact, it may not even be the best choice for the program examined in this book. However, to ground the abstraction, a concrete language had to be selected. I chose C++ because it is standardized, widely deployed, and available at zero cost on many platforms. Selfishly, I also chose C++ because it is my most proficient language. While I could, perhaps, have chosen another language meeting the aforementioned objective criteria (e.g., Python), the resulting code would probably have been functional but nonidiomatic due to my relative lack of expertise.

During the writing of the first edition of this book, C++0x was ratified as C++11 and then updated as C++14. C++11, with smart pointers, move semantics, lambdas, variadic templates, and a host of other new features, fundamentally changed how one could express a design in the C++ language. My objective at the time was to avoid incorporating modern C++ features where they were inappropriate just to demonstrate usage. Instead, I sought to highlight how these new language elements could be used effectively in the design of a large-scale program. Hopefully, I achieved my objective.

Design and architecture have not changed significantly since the publication of the first edition of this book, so why write a second edition? If this were an abstract design book, such an update would be unnecessary. However, since the publication of the first edition, C++17 and C++20 were both ratified. Because the book’s case study is accompanied by a complete implementation, expressing a concrete design using C++ has evolved with new language developments. While C++17 added several new implementation features, none of these features substantially impacted the ability to express designs in the language. C++20, on the other hand, is different.

C++20, maybe even more so than C++11, fundamentally changes how designs may be expressed in C++. In particular, four new major language features were added: ranges, coroutines, concepts, and modules, all of which make, at least, a brief appearance in the case study. The ranges library does not fundamentally alter program design. It does, however, fundamentally change the way algorithms can be implemented, especially with the better integration of the functional programming paradigm as enabled through views. Coroutines add cooperative multitasking to the C++ language. We will see that even in a single-threaded program such as the one described in this book, coroutines can be used to express an idea from the first edition differently. Concepts change the way generic programs are constructed. This book’s design does not make extensive use of templates; therefore, concepts make only the briefest of appearances. Lastly, C++20 finally brings modularization to C++ as a formal language construct. This change drastically impacts how code can be organized, including, in many instances, completely eliminating the need for header files. We will explore the usage of C++ modules, and their interaction with dynamically linked libraries, in some depth.

In the second edition, I again endeavor to illustrate the interplay between implementation and design and hence aim to demonstrate how language features enable the more natural expression of design paradigms. Where the design usage of modern C++ language or library features are generalizable beyond the case study, I have chosen to highlight these points in a sidebar. Sidebars are inclusive of all new language features since C++11.

GUI Framework, Tooling, External Dependencies, and Compilers

While graphical user interfaces (GUI) are not the primary focus of this book, our program will eventually acquire one; hence, selecting a particular GUI framework was necessary. I selected Qt for this purpose and successfully tested the code against Qt versions 5 and 6. As with C++, Qt is widely deployed, cross platform, and free. As with C++, again, selfishly, I chose Qt because I am experienced using desktop Qt and personally enjoy using it. A big advantage of using Qt is that it makes nearly all of the source code for the project platform independent. Where platform independence was not achievable, I encapsulated the platform-dependent code behind an abstract interface. We’ll explore this design pattern, in depth, in Chapter 7.

In the first edition of this book, pdCalc was mostly self-contained, from both a code and tooling standpoint; Qt was the only external dependency necessary to compile, build, and test the code. For the second edition, however, a few external dependencies were necessary. First, I changed the build system from using Qt’s own qmake to Kitware’s CMake [1]. CMake is cross platform, free of charge, easy to obtain, and practically a de facto standard for building C++ applications. For my purposes, CMake made experimentation with different C++20 compilers easier and more efficient. Of note, CMake’s C++20 tooling for modules was still immature at the time of writing, so some parts of the build scripts are more imperative than I expect will be necessary in the future. Second, while C++20 added coroutines as a new low-level language feature, the standard did not incorporate any high-level supporting libraries. In order to focus on the design aspects of using coroutines rather than their implementation mechanics, I increased the level of abstraction by using Lewis Baker’s cppcoro [7] library to implement a generator (see Chapter 5). For convenience, I included the single necessary file from cppcoro into a third-party directory included with pdCalc’s source code.

In general, I always strive to write standards-conforming, platform-independent code. Since any known platform-specific code is compartmentalized and encapsulated, extension to other platforms should be straightforward if you can tolerate the pain of customizing the build system. Therefore, the source code in this book should compile with any C++20-compliant compiler and on any platform where Qt is supported. Unfortunately, over a year after finalization of the standard, only one compiler, Microsoft’s Visual C++ (MSVC), is sufficiently standards conforming to actually compile the full source code presented in this book. (To be fair, 2020 was a very strange year.) GCC is close, but it lacks two key features. First, GCC’s C++ standard library implementation is missing the C++20 formatting library. This problem can be easily remedied by substituting the MIT licensed fmt library [2] in its place. The bigger problem is the immaturity of C++ modules support in GCC. Specifically, pdCalc’s source code, at the time of writing, causes GCC to produce internal compiler errors; I have submitted multiple bug reports. Clang’s support of C++20, while laudable, is behind both GCC and MSVC. At the current pace of development, I expect GCC to reach sufficient standards conformance to compile this book’s source code ahead of clang.

The Source Code

The source code (and supporting unit tests) for pdCalc is available, in its entirety, from Apress’s GitHub repository (https://github.com/Apress/practical-cplusplus-design-2e). Appendix A describes, in detail, how to download and build the source code. Although most readers will likely prefer to download the source using a git client, the entire source code is also available from GitHub as a single zip file.

The source code itself is licensed under the GNU Public License (GPL) version 3. I hope you find the source code useful for learning about design and implementation. Beyond its use as an educational aid for this book, you are, of course, free to do anything you like with the source code within the rights granted to you by the GPL.

For the first edition of this book, I wrote the source code for pdCalc from scratch specifically targeting new language features of C++11; the source code was updated for C++14 shortly before publication. For the second edition of this book, I updated and refactored the source code to use C++17 and C++20 features instead of performing a complete rewrite. This strategy has two implications. First, not every line of code was touched, although more lines were touched than I originally anticipated. Nevertheless, I likely missed places where newer features of the language could have been used but weren’t. In other instances, newer features were intentionally not used because of compiler or language support. For example, while most of pdCalc was upgraded to extensively use modules, the GUI was not because, at the time of writing, modules and Qt’s meta object compiler (MOC) did not interoperate well. Second, because I was literally refactoring the source code for the sole purpose of incorporating new language features, I was able to identify specifically where new language features enabled different design paradigms. Where these changes were significant, I contrasted the original version of the source code and its design to the updated version directly in the book’s text.

In general, I tried to reproduce the code in the text identically to the code in the repository. However, in some cases, parts of the source were deliberately omitted in the text either for brevity or clarity. I tried to note instances where the differences are significant. Where the two differ, assume the code in the repository is the more correct and complete version.