Struct versus Class Default Access When Exposing Types Across a Library Boundary

Direct Answer

Use class (or an explicit private: section in a struct) for opaque types in public headers. struct defaults to public member and base-class access, which lets callers legally depend on implementation details. class defaults to private, preventing accidental exposure and preserving the library's freedom to change internals without breaking the ABI—provided the type's definition remains hidden and only forward-declared in the header.

Confirmed Facts

• Default access differs: struct members and bases are public by default; class members and bases are private by default.
• Binary layout is identical: The keyword choice does not change object size, alignment, or member ordering when the same members are declared in the same order.
• Access control is compile-time only: It prevents callers from naming private members, but does not hide the members' existence from the type's layout if the full definition is visible in the header.

Risks of Using struct for Opaque Types

1. Accidental dependency: Callers can legally access any data member or base class not explicitly marked private:. If the library later adds a helper field or changes a base, existing binaries that happened to use that member will break or exhibit undefined behavior.
2. ABI fragility: Even if the library never intends callers to touch internals, the public default makes it syntactically valid. A future maintainer adding a member without adding private: instantly expands the public surface.
3. Documentation drift: The header itself becomes misleading—readers see public members and assume they are part of the contract.

Recommended Decision Process

1. Is the type a handle (pointer to incomplete type)? Forward-declare only: class Foo; or struct Foo;—keyword irrelevant. Stop here.
2. Must the full definition be in the header? (e.g., value type returned by value, used in templates, or needing sizeof in client code.) If yes, use class and explicitly mark any public interface with public:. If no, forward-declare and define in the .cpp file.
3. If you prefer struct for style: Immediately add private: before any data members. Treat it identically to class.

Verification Steps

• Compile client code that attempts to access a data member of the opaque type. With class (or struct + private:) the compile fails; with plain struct it succeeds.
• Run abi-compliance-checker or similar on two library versions where a private data member is added. Confirm no ABI break when the type is properly encapsulated.

One Missing Detail

Does the opaque type need to be a complete type in the header (e.g., returned by value, stored directly in client containers, or used as a template argument)? If yes, the full definition must be visible and class with explicit public: for the intended interface is the safe default. If no, forward-declare and avoid the question entirely.