SPERR Style Guide

(This is a collection of style guidelines that are not very well organized yet.)

1. Use the AAA (Almost Always Auto) style. More discussion on this style can be found on this Herb Sutter's post.
2. When using macros (e.g. #ifdef QZ_TERM) for selected compilation, if there's only one section (i.e., no #else or #elif) then don't add a blank line just for the macros. If there are more than one section (i.e., with #else or #elif) then use a blank line before #ifdef and after #endif.

How About Raw Pointers?

SPERR strongly discourages the use of raw pointers in its code base for safety, performance, and other reasons. Instead, programmers should consider using smart pointers (mostly std::unique_ptr<>) and containers (e.g., std::vector<>). However, there are a few exceptional cases where raw pointers make a lot more sense and they can be used. Overall, the use of raw pointers needs to be looked at on a case-by-case basis

When to Use Raw Pointers?

1. When SPERR interacts with other projects and they might give SPERR a raw pointer.
   • Example: when SPERR takes in input from NetCDF libraries, and NetCDF provides a raw pointer.
   • Example: when SPERR calls ZSTD compression routines.
2. When SPERR has to interact with C libraries that use raw pointers.
   • Example: when SPERR calls fread() and fwrite() from cstdio. (This isn't really a good example because we should look into using fstreams provided by C++.
   • Example: when SPERR provides a C API to others.
3. When doing type punning stuff.
   • Example: when SPERR puts 8 bytes representing a double to an arbitrary position in an output stream.
   • Example: when SPERR reads in a file from disk as uint8_ts, and treats the stream as double or float values.
4. When SPERR borrows code from other open-source projects and it's hard to convert it away from raw pointers.
   • Example: SPERR uses wavelet transform code from QccPack, which is written using raw pointers, and it's a little tricky (but not impossible), to convert.

Q&A

1. Q: If I want to specify a function to process a specific range of a long array, what are my options?
   • A: Pass in the begin and end iterators of the range. This is the convention of modern C++.