clang-format Evaluation for xtd (internal)

Purpose

This document summarizes the evaluation of clang-format as a potential alternative to astyle for formatting the xtd codebase.

The goal was to determine whether clang-format could match the strict and elegant formatting style currently used in xtd, and whether it would be a viable replacement in terms of configuration flexibility and output.

---

CMake command

option(XTD_DOWNLOAD_CLANG_FORMAT "Download and build clang-format from Github" OFF)
option(XTD_ENABLE_RUN_CLANG_FORMAT "Enable run clang-format (format) command" OFF)

################################################################################
# Run clang-format command

if (XTD_ENABLE_RUN_CLANG_FORMAT AND NOT RUN_CLANG_FORMAT_ONLY_ONCE)
  set(RUN_CLANG_FORMAT_ONLY_ONCE TRUE)
  find_program(CLANG_FORMAT_EXE NAMES clang-format)

  if (CLANG_FORMAT_EXE AND XTD_ENABLE_RUN_CLANG_FORMAT)
    file(GLOB_RECURSE CLANG_FORMAT_SOURCE_FILES
      ${CMAKE_SOURCE_DIR}/*.cpp
      ${CMAKE_SOURCE_DIR}/*.hpp
    )

    add_custom_target(run_clang_format
      COMMAND ${CLANG_FORMAT_EXE} -i -style=file ${CLANG_FORMAT_SOURCE_FILES}
      COMMENT "Running clang-format"
    )
    set_target_properties(run_clang_format PROPERTIES FOLDER commands)
  endif()
endif ()

These CMake lines are used to add the run_clang_format compilation target.

Configuration Used

BasedOnStyle: Google
IndentWidth: 2
UseTab: Never
ColumnLimit: 0
AlignConsecutiveAssignments: false
AlignConsecutiveDeclarations: false
AllowShortEnumsOnASingleLine: true
AllowShortFunctionsOnASingleLine: All
BreakBeforeBraces: Custom
BraceWrapping:
  AfterEnum: false
  AfterStruct: false
  AfterClass: false
  AfterControlStatement: false
  SplitEmptyFunction: false
  SplitEmptyRecord: false
  SplitEmptyNamespace: false
SpacesInParentheses: false
SpaceBeforeParens: ControlStatements
SpaceInEmptyParentheses: false
SpaceBeforeCpp11BracedList: true

This configuration aimed to match xtd’s current formatting as closely as possible.

---

Incompatibilities Found

Despite a close attempt, several stylistic mismatches were observed:

1. Enums on a Single Line

Source:

enum Color { red, green, blue };

Formatted as:

enum Color { red,
             green,
             blue };

✅ Expected to stay compact if originally written in one line.

---

2. Enums Multiline Style

Source:

enum Color {
    red,
    green,
    blue};

Desired formatting:

enum Color {
  red,
  green,
  blue};

❌ clang-format either indents closing brace incorrectly or applies inconsistent spacing.

---

3. Spacing in Braced Constructors

Source:

xtd::forms::application::run(xtd::forms::form {});

Formatted as:

xtd::forms::application::run(xtd::forms::form{});

❌ The space between type and {} is removed, breaking xtd style.

---

4. Declaration Alignment

Source:

auto main_form = form::create("Gui application");
auto info_label = label::create(main_form, "...", {10, 10});

Formatted as:

auto main_form         = form::create("Gui application");
auto info_label        = label::create(main_form, "...", {10, 10});

❌ Unwanted alignment of assignment operators — xtd prefers natural spacing, not column-based alignment.

---

5. Access Specifier Formatting

Source:

class test_class_(test_application) {
public:
  // ...
};

Formatted as:

class test_class_(test_application) {
 public:
  // ...
};

❌ Space before public: is not allowed in xtd style.

---

Conclusion

Although clang-format is powerful and widely adopted, it lacks the fine-grained control and stylistic nuance required by the xtd codebase. Many of xtd's formatting rules are contextual, minimalist, and intentionally designed, which clang-format cannot currently express — even with extensive configuration.

Given these limitations:

❌ clang-format is not suitable for xtd at this time.
✅ xtd will continue using astyle as it better respects the project's formatting philosophy.

---

Future Possibilities

• Revisit clang-format if more granular options are added in future versions.
• Explore writing a custom formatter or wrapper if needed.
• Consider using clang-format only for CI linting or limited to trivial files (unlikely in xtd's case).

---