C++ Style Guide

This article specifies the most general guidelines used for all Spire projects written using C++ as the primary programming language. Each individual project may extend or override the guidelines specified herein. The overall aim of this guideline is to provide consistency across the numerous projects developed by Spire in order to promote and benefit from modern C++ practices as well as tailor them to our specific requirements.

In general, the guidelines are very specific and opinionated. This is done intentionally to ensure that every detail has been given proper consideration and that every line of code is written with care and diligence. It is taken as a prerequisite that writing robust, clean and maintainable code requires paying close attention to even the smallest of details. As such, when there are two or more ways to write or express any given statement or expression, be it using spaces or tabs, number of characters per line, purple or violet, the guideline will often require that one particular approach be used to the exclusion of others.

Finally, this document is constantly evolving and as such older projects may not be up-to-date with the guidelines found here. In those circumstances one must use their best judgment about how to integrate these guidelines into older codebases. As a general principle, consistency should favor the local over the global, that is it is more important to be consistent with a function definition than within a file, and more important to be consistent within a file than within a directory, project, etc...

Core Guidelines

This document should be seen as an extension to the Cpp Core Guidelines authored and maintained by Herb Sutter and Bjarne Stroustrup. After reviewing these guidelines one should then become familiar with the Cpp Core Guidelines as documented here:

https://github.com/isocpp/CppCoreGuidelines

Those guidelines specify the best practices for writing modern C++ code. In situations where there is a conflict between the Cpp Core Guidelines and the guidelines set forth in this document, this document takes precedence. For all known situations where a conflict exists, this document should explicitly indicate that conflict to avoid confusion.

Development Environment

The two primary development environments supported by Spire projects are Ubuntu Server 16.04 LTS and Windows 10. On Unix like systems the compiler of choice is g++ 5.4 and on Windows 10 it's Microsoft Visual Studio 2017 15.5.5. In order to support these two platforms, CMake is used to produce the appropriate project/make files for each platform.

For source control, git is used and projects are to be hosted on Spire Trading's Github page.

Each developer is welcome to use an editor of their choice. Visual Studio 2017 is typically used for Windows and Visual Studio Code is typically used on Linux and Mac.

File Names

Use snake case using all lower case letters for files and directories. The main exception is for CMake files which must use the name "CMakeLists.txt"

Header files should use the extension ".hpp"

Source files should use the extension ".cpp"

Directory Structure

A project is typically broken down into a library component and an application component. Assuming a project named chat consisting of applications chat_server and chat_client sharing code common to both applications, the following directory structure should be used:

chat_project                       # Root level directory.
  \applications                    # Contains all applications.
    \chat_server                   # Contains the chat server application.
      \build                       # Files/scripts used to build the chat server.
        \config                    # Contains all CMake build files.
          CMakeLists.txt           # The CMake config file for the overall application.
          \chat_server             # Contains CMake build files for the main executable.
            \CMakeLists.txt        # The CMake config file for the executable.
        \make                      # Contains scripts to build on POSIX systems.
          \build.sh                # Script used to build the application.
          \run_cmake.sh            # Script used to produce the make/build files.
          \set_env.sh              # Script defining the environment variables.
          \version.sh              # Script that produces the VERSION stamped header file.
        \windows                   # Contains scripts to build on Windows.
          \build.bat               # Script used to build the application.
          \run_cmake.bat           # Script used to produce the VS solution.
          \set_env.bat             # Script defining environment variables.
          \version.bat             # Script that produces the VERSION stamped header file.
      \source                      # Contains the C++ source files.
        \chat_server               # Contains the file defining the main function.
          \main.cpp                # Defines the main function.
        \source_dir_a              # Contains additional source files specific the the server.
          \source_a.cpp            # C++ source code files.
          \source_b.cpp
          \source_c.cpp
        \source_dir_b              # Contains additional source files specific the the server.
          \source_d.cpp
          \source_e.cpp
          \source_f.cpp
    \chat_client                   # Contains the chat client application.
      \...                         # The structure is similar to the server application.
  \build                           # Contains build scripts to build the entire project.
    \make                          # Contains scripts to build on POSIX systems.
      \build.sh                    # Builds all libraries and applications.
      \local_build.sh              # A helper script containing common build functions.
      \run_cmake.sh                # Produces all project make/build files.
      \setup.sh                    # Installs all third party dependencies.
    \windows                       # Contains scripts to build on Windows.
      \build.bat                   # Builds all libraries and applications.
      \run_cmake.bat               # Produces all VS solutions.
      \setup.bat                   # Installs all third party dependencies.
  \library                         # Contains the common library code.
    \build                         # Files/script used to build the library.
      \config                      # Contains all CMake build files.
        \CMakeLists.txt            # The CMake config file for the library.
        \dir_a                     # Contains CMake build files for library component A.
          \CMakeLists.txt          # The CMake config file to build component A and unit tests.
        \dir_b                     # Contains CMake build files for library component B.
          \CMakeLists.txt          # The CMake config file to build component B and unit tests.
      \make                        # Contains scripts to build on POSIX systems.
        \build.sh                  # Script used to build the library.
        \run_cmake.sh              # Script used to produce make/build files.
        \set_env.sh                # Script defining the environment variables.
      \windows                     # Contains scripts to build on Windows.
        \build.bat                 # Script to build the library.
        \run_cmake.bat             # Script to produce the VS solution.
        \set_env.bat               # Script defining the environment variables.
    \include                       # Contains the library header files (.hpp)
      \chat_project                # Same as above.
        \chat_project              # Contains the top-most generic library header files.
          \chat_project.hpp        # Header file containing generic forward declarations.
        \dir_a                     # Contains header files for library component A.
          \a.hpp                   # Header file containing forward declarations for component A.
          \a_header_1.hpp          # Header file for library component A.
          \a_header_2.hpp
          \a_header_3.hpp
        \dir_b
          \b.hpp                   # Header file containing forward declarations for component B.
          \b_header_1.hpp          # Contains header files for library component B.
          \b_header_2.hpp
          \b_header_3.hpp
    \source                        # Contains the library source files (.cpp)
      \chat_project                # Dummy directory for the overall library.
        \dummy.cpp                 # Dummy source code file.
      \dir_a                       # Dummy directory for library component A.
        \dummy.cpp                 # Dummy source file.
      \dir_a_tester                # Contains unit tests for library component A.
        \a_header_1_tester.cpp     # Contains unit tests for definitions in a_header_1.hpp
        \a_header_2_tester.cpp
        \a_header_3_tester.cpp
        \main.cpp                  # The entry point for component A unit tests.
      \dir_b                       # Dummy directory for library component B.
        \dummy.cpp                 # Dummy source file.
      \dir_b_tester                # Contains unit tests for library component B.
        \b_header_1_tester.cpp     # Contains unit tests for definitions in b_header_a.hpp
        \b_header_2_tester.cpp
        \b_header_3_tester.cpp
        \main.cpp                  # The entry point for component B unit tests.