For a C++ library's public API, what parameter-passing convention would you set for your team, and how would you handle optional and in-out parameters?
answer
- in, in-out, out, sink
- cheap by value, expensive by const&
- pointer when absence is valid
- return values over out-parameters
- enforce with review and tooling
basics
~20 sClassify each parameter by role: cheap inputs by value, expensive inputs by const&, in-out by non-const reference, optional inputs by pointer, outputs as return values, consumed values by value. Write it down and enforce it with review and lint checks.
solid answer
~40 sI would publish a short table keyed by the parameter's role, close to the C++ Core Guidelines' F.16-F.20 and F.60. Inputs: by value when cheap to copy (a few machine words, trivially copyable - `Point`, `std::string_view`, `std::span`), otherwise `const T&`. In-out: `T&`, so callers must pass a real object. Outputs: return them - a struct, `std::pair` or `std::expected` (C++23) - rather than out-parameters. Optional inputs: `const T*`, where `nullptr` means "none", until `std::optional<T&>` from C++26 is available on every target. Sink parameters the callee stores: by value, then move. Accessors return `const T&` only to state the object owns, documenting that the reference dies with the object. The trade-offs are call-site readability versus non-nullability, ABI stability and how much the team can enforce with tools.
go deeper
Recall the basic split: small types by value, large read-only types by const reference, and a non-const reference only when the function changes the argument.
Explain each role in the table - input, in-out, output, optional, sink - and why a pointer, not a reference, signals that an argument may be absent.
Apply the convention in reviews, recognize sink parameters, avoid out-parameters in favour of return values, and spot accessors returning references that can dangle.
Choose and defend the trade-offs - call-site visibility versus non-nullability, overload count versus one extra move, toolchain support for optional<T&> - and enforce them with tooling.
## Why a convention is a lead's decision A public API is read far more often than it is written, and every signature is both a performance decision and a contract. Without a team rule, a geometry library ends up with `scale(Point)`, `scale(const Point&)`, `scale(Point&)` and `scale(Point*)` meaning the same thing in different headers. The language allows all of them; the decision is which ones carry which promise, and there is no single right answer - only trade-offs that a lead must pick and enforce. ## A convention keyed by role | Role | Spelling | Rationale | |---|---|---| | input, cheap to copy | `Point p`, `int n`, `std::string_view s`, `std::span<const float> s` | no indirection, no aliasing; views are cheap by design | | input, expensive to copy | `const Mesh& m` | avoids the copy; accepts temporaries | | input, may be absent | `const Mesh* m` (`nullptr` = none) | the pointer's null state is the meaning | | in-out | `Mesh& m` | must be a real object; temporaries rejected at compile time | | output | return value, a struct, or `std::expected<T, E>` (C++23) | composable, no uninitialized out-variables | | sink (callee keeps it) | `std::string name` then move into the member | one copy or one move depending on the caller | | ownership transfer | a smart pointer by value | covered with the ownership material | This is close to the C++ Core Guidelines' function rules: F.16 (cheap inputs by value, others by `const&`), F.17 (in-out by non-const reference), F.20 (prefer return values to output parameters) and F.60 (prefer `T*` over `T&` when "no argument" is valid). Citing a public reference saves arguments in review. ## The contested choices 1. **Out-parameters as pointer or reference?** Some codebases require `Mesh*` for anything the callee modifies so the `&` at the call site makes mutation visible. The cost is a null state the callee must handle. The convention above uses `Mesh&` and relies on names (`fill_normals(mesh)`) and return values to keep mutation obvious. Pick one; mixing them is the worst outcome. 2. **Optional inputs: pointer or optional?** `std::optional<T>` copies the value, so it is right only for cheap types. `std::optional<T&>` arrives in C++26 and expresses "maybe a reference" without the arithmetic and ownership ambiguity of a raw pointer, but until every supported toolchain ships it, `const T*` documented as non-owning is the portable choice. 3. **The size threshold for by value.** "Up to two or three machine words and trivially copyable" follows common 64-bit ABIs, which pass small aggregates in registers. It is an ABI fact, not a language rule, so a cross-platform library states the threshold in bytes and accepts that the edge cases differ per target. 4. **Sink parameters.** By value plus `std::move` costs one extra move compared to a pair of `const T&` / `T&&` overloads, in exchange for half the overloads. Most teams take that trade outside the hottest code. ## Returning references Accessors are part of the convention too: - return `const T&` to an object the class owns, e.g. `const Point& center() const`, so reading is cheap - and document that the reference is valid only while the owner lives and is not modified; - return by value for small types and for anything computed; - never return a reference to a local or to a parameter that may have bound a temporary - those are dangling-reference bugs, covered with dangling and use-after-free. ## ABI and evolution For a library shipped as a binary, changing `Point` to `const Point&` (or back) changes the mangled name and the calling sequence - an ABI break. Getting the convention right before 1.0 matters more than optimizing it later; the material on name mangling and ABI covers what else breaks binaries. ## Enforcement - Write the table into the contribution guide and link it from review checklists. - Turn on clang-tidy's `performance-unnecessary-value-param` (flags expensive by-value inputs that are only read) and `modernize-pass-by-value` (suggests by-value sinks). - Add a review rule that any `T&` parameter must be modified in the function, otherwise it should be `const T&`. - Revisit the optional-input rule when the minimum toolchain gains `std::optional<T&>`.
- Why prefer returning a struct or std::expected over output reference parameters?A return value cannot be forgotten or left uninitialized, composes with `auto` and structured bindings, and benefits from guaranteed copy elision for prvalues in C++17. Output parameters force callers to declare a variable first, hide which arguments are written, and complicate error handling. `std::expected<T, E>` (C++23) returns either the value or an error in one object, replacing the bool-plus-out-parameter idiom.
- When is a non-const reference parameter still the right choice over returning a value?When the callee updates a large existing object in place - appending to a buffer, filling a pre-sized mesh, advancing a parser's state - so returning a new object would copy or reallocate what the caller already owns. The convention names it in-out, uses `T&`, and expects a name that says it mutates.
- Everything except ints should be passed by const reference
- Out-parameters should always be references because pointers can be null
- std::optional<T> is the right way to pass an optional large input
- Parameter-passing style is personal taste and needs no team rule
- Changing a public function from by-value to const& keeps binary compatibility
Assumes C++23 for std::expected; std::optional<T&> is a C++26 addition not yet available on every toolchain.