This section provides some information about some of the abstractions and development approaches we use to solve problems common to many parts of the C++ project.
C++ source and header files should use underscores for word separation, not hyphens.
Compiled executables, however, will automatically use hyphens (such that
src/arrow/scalar_test.cc will be compiled into
C++ header files use the
.h extension. Any header file name not
internal is considered to be a public header, and will be
automatically installed by the build.
We provide a default memory pool with
Error Handling and Exceptions¶
For error handling, we return
arrow::Status values instead of throwing C++
exceptions. Since the Arrow C++ libraries are intended to be useful as a
component in larger C++ projects, using
Status objects can help with good
code hygiene by making explicit when a function is expected to be able to fail.
A more recent option is to return a
arrow::Result<T> object that can
represent either a successful result with a
T value, or an error result
For expressing internal invariants and “cannot fail” errors, we use
arrow/util/logging.h. These checks are disabled in release builds
and are intended to catch internal development errors, particularly when
refactoring. These macros are not to be included in any public header files.
Since we do not use exceptions, we avoid doing expensive work in object
constructors. Objects that are expensive to construct may often have private
constructors, with public static factory methods that return
There are a number of object constructors, like
arrow::RecordBatch where larger STL container objects like
be created. While it is possible for
std::bad_alloc to be thrown in these
constructors, the circumstances where they would are somewhat esoteric, and it
is likely that an application would have encountered other more serious
problems prior to having
std::bad_alloc thrown in a constructor.
Comments and Docstrings¶
Regular comments start with
Doxygen docstrings start with
///, and Doxygen directives start with
\, like this:
The summary line of a docstring uses the infinitive, not the indicative (for example, “Allocate a buffer” rather than “Allocates a buffer”).