Cross‑Platform C++ Development Pitfalls Guide

This article provides a practical guide for avoiding common pitfalls when developing C++ code that must compile and run on multiple platforms (Windows, macOS, Linux) and devices (desktop, mobile). It is organized as a series of best‑practice recommendations, each accompanied by concise explanations and code examples.

Why multi‑platform development is hard

Two main reasons cause complexity: differences between operating systems and undefined behavior across compilers. The guide addresses both.

C++ version selection

Use the latest stable standard (C++17 at the time of writing) to benefit from newer library features and reduce platform‑specific code.

Prevent duplicate header inclusion

#pragma once
#include <vector>
...

or

#ifndef FOO_BAR_BAZ_H_
#define FOO_BAR_BAZ_H_
...
#endif // FOO_BAR_BAZ_H_

Path separators

Always use forward slashes (/) and match case exactly on case‑sensitive systems (Linux/macOS).

C standard library headers

Explicitly include required C headers in both .c and .cpp files to satisfy C99 and later standards.

File encoding

Save source files as UTF‑8 with BOM to avoid garbled characters on different platforms.

Inline functions

Use inline only for short functions; avoid over‑inlining on mobile where code size matters. Follow guidelines such as limiting inline functions to fewer than 10 lines.

Basic type definitions

typedef std::int8_t  int8;
typedef std::int16_t int16;
typedef std::int32_t int32;
typedef std::int64_t int64;

typedef std::uint8_t  uint8;
typedef std::uint16_t uint16;
typedef std::uint32_t uint32;
typedef std::uint64_t uint64;

Prefer standard types over custom aliases to avoid redefinition and ambiguity.

Char and wchar handling

Specify signedness for char and avoid wchar_t in cross‑platform code; use UTF‑8 string literals (u8"...") instead.

Avoid consecutive angle brackets std::vector<std::vector<int> > vec; or use a typedef to improve readability. C++11 resolves the issue, but older compilers may still need a space.

Platform‑specific code

Wrap small differences in #ifdef blocks; for larger differences, split into separate source files (e.g., foo_win.cpp, foo_mac.cpp, foo_linux.cpp).

Compiler choice

Prefer Clang for its fast compilation, clear diagnostics, and strict checks, which help maintain portable code.

Conversion layer

Keep conversion layers (e.g., C++↔Objective‑C, C++↔Java) free of business logic; treat them as glue code. Tools like Djinni can automate this.

Assert usage

#ifdef NDEBUG
#define ALOG_ASSERT(_Expression) ((void)0)
#else
#define ALOG_ASSERT(_Expression) do { \
    // optional logging
    if (HandleAssert()) { \
        assert(_Expression); \
    } \
} while (false)
#endif

Redefine assert to control behavior on mobile and Unix‑like systems.

Inheritance and composition

Prefer composition over inheritance; when inheritance is needed, make it public and use override/final for virtual functions.

Static variables

Be aware of static initialization order and thread‑safety; consider using function‑local statics or avoid globals when possible.

Template usage

Limit templates in mobile builds to control binary size; use small template units or replace with concrete implementations when feasible.

Overall recommendation

Follow the Google C++ Style Guide and the listed best practices to achieve consistent, maintainable, and efficient cross‑platform C++ code.