Essential C++ Cross‑Platform Pitfalls and How to Avoid Them

The author, a C++ developer with two years of multi‑platform experience, writes this guide after spending two months on a Windows project and another week adapting the same code to macOS. The goal is to provide a concise set of effective C++ practices that help keep a single codebase consistent across different platforms and compilers.

Cross‑platform development complexity mainly stems from two sources:

Platform differences under multiple operating systems.

Uncertain behavior across different compilers.

Both issues are addressed throughout the guide, and the Google C++ Style Guide is recommended as a primary reference.

1. Choose the Right C++ Version

Use the latest stable standard that your toolchain supports; C++17 is recommended because it provides many useful features that reduce platform‑specific code.

2. Prevent Duplicate Includes

Two common techniques avoid multiple inclusion of the same header:

Use #pragma once (widely supported by clang, MSVC, etc.).

Use traditional include guards:

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

3. Path Separators

Windows accepts both backslashes and forward slashes, while Linux only accepts forward slashes and is case‑sensitive. Always use forward slashes and match the exact case of the filesystem.

4. C Standard Library Headers

Some C headers are implicitly included on Windows but must be explicitly included on Linux. Include all required headers directly in each .c/.cpp file.

5. File Encoding

Use UTF‑8 with BOM for all source files, especially when they contain Chinese characters, to avoid encoding issues on different platforms.

6. Inline Functions

Inline functions can improve performance for small bodies but may increase binary size on mobile devices and cause unexpected behavior across modules. Recommended guidelines:

Avoid inline functions longer than ten lines.

Use inline only for simple getters.

Mark inline functions with appropriate qualifiers (e.g., const).

Do not inline custom destructors.

7. Basic Type Definitions

Avoid custom typedefs for fundamental types; use the standard int8_t, uint32_t, etc., directly to prevent redefinition conflicts.

8. Char Definition

Explicitly specify signed or unsigned for char. Different compilers treat plain char differently, which can cause subtle bugs during implicit conversions.

9. Wide Characters

On Windows, wchar_t is 2 bytes; on Linux it is 4 bytes. This leads to size differences, portability problems, and unexpected conversion results. Prefer UTF‑8 strings (using u8"") and avoid wchar_t unless absolutely necessary.

10. String Literal Encoding

Prefix string literals with u8 to enforce UTF‑8 encoding, especially for Chinese text. Do not use u8 on character literals.

11. Consecutive Angle Brackets

For nested templates, either insert a space between the two > symbols or create a typedef to improve readability. C++11 resolves this syntax issue.

12. Platform‑Specific Code

Use #ifdef guards for short platform‑specific sections; for larger functionality, split files by platform (e.g., foo_win.cpp, foo_mac.cpp, foo_linux.cpp).

13. Non‑Standard Compiler Keywords

Avoid Microsoft‑specific keywords such as __super, __wchar_t, __stdcall, etc., to maintain portability.

14. Assert Usage

Standard assert can be too aggressive on mobile/Unix platforms. Redefine assert to a custom macro that logs errors and optionally aborts, based on build configuration.

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

15. Inheritance vs. Composition

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

16. Static Variables

Be aware of the order of dynamic initialization and destruction, especially in multithreaded contexts. Consider replacing global static objects with function‑local statics to avoid destruction‑order crashes.

// old
static std::recursive_mutex& m_mutex;
// new
static std::recursive_mutex& mutex() {
    static std::recursive_mutex* m = new std::recursive_mutex();
    return *m;
}

17. Templates

Templates can cause code bloat, which is problematic for mobile builds. Recommendations:

Avoid templates unless they provide clear benefits (e.g., JSON serialization).

Prefer small template compilation units or move templates into class methods.

Limit explicit specializations to reduce binary size.

Replace template‑heavy base classes with non‑template interfaces when possible.

18. Compilers

Familiarize yourself with clang, MSVC, and gcc. clang offers fast compilation, clear diagnostics, and strict code checks, making it a good default choice for cross‑platform C++ development.

19. Conversion Layer

The conversion layer (e.g., C++↔Objective‑C, C++↔Java) should contain no business logic. Treat it as glue code; tools like Djinni can help generate such layers.

By following these guidelines, developers can reduce platform‑specific bugs, keep binary size under control, and improve maintainability of multi‑platform C++ projects.