File Naming#

C++ source and header files should use underscores for word separation, not hyphens.Compiled executables, however, will automatically use hyphens (such thate.g.src/arrow/scalar_test.cc will be compiled intoarrow-scalar-test).

C++ header files use the.h extension. Any header file name notcontaininginternal is considered to be a public header, and will beautomatically installed by the build.

Comments and Docstrings#

Regular comments start with//.

Doxygen docstrings start with///, and Doxygen directives start with\,like this:

/// \brief Allocate a fixed size mutable buffer from a memory pool, zero its padding.////// \param[in] size size of buffer to allocate/// \param[in] pool a memory poolARROW_EXPORTResult<std::unique_ptr<Buffer>>AllocateBuffer(constint64_tsize,MemoryPool*pool=NULLPTR);

The summary line of a docstring uses the infinitive, not the indicative(for example, “Allocate a buffer” rather than “Allocates a buffer”).

Memory Pools#

We provide a default memory pool witharrow::default_memory_pool().

Error Handling and Exceptions#

For error handling, we returnarrow::Status values instead of throwing C++exceptions. Since the Arrow C++ libraries are intended to be useful as acomponent in larger C++ projects, usingStatus objects can help with goodcode hygiene by making explicit when a function is expected to be able to fail.

A more recent option is to return aarrow::Result<T> object that canrepresent either a successful result with aT value, or an error resultwith aStatus value.

For expressing internal invariants and “cannot fail” errors, we useDCHECK macrosdefined inarrow/util/logging.h. These checks are disabled in release buildsand are intended to catch internal development errors, particularly whenrefactoring. These macros are not to be included in any public header files.

Since we do not use exceptions, we avoid doing expensive work in objectconstructors. Objects that are expensive to construct may often have privateconstructors, with public static factory methods that returnStatus orResult<T>.

There are a number of object constructors, likearrow::Schema andarrow::RecordBatch where larger STL container objects likestd::vector maybe created. While it is possible forstd::bad_alloc to be thrown in theseconstructors, the circumstances where they would are somewhat esoteric, and itis likely that an application would have encountered other more seriousproblems prior to havingstd::bad_alloc thrown in a constructor.