clang-hesong

C/C++ identifier renaming (snake_case / camelCase / PascalCase) and optional code cleanup — VS Code extension (Windows x64). Right-click a file → clang-hesong: Run On This File → rewrites the file on disk per .vscode/clang-hesong.json.

Publisher: HeSong Tools · Platform: Windows only · Not affiliated with LLVM / Microsoft C/C++.

Contents

1. Configuration

Config JSON keys are the features. File: .vscode/clang-hesong.json (create via clang-hesong: Open Config). The extension sets input_output_file automatically — do not add input_dir / output_dir (CLI only).

*Required for real multi-file projects when renaming module API at call sites.

Example (placeholders — replace paths):

{
  "naming_style": "snake",
  "this_module_include_dirs": [
    "C:\\fake-dir1\\src",
    "C:\\fake-dir2\\include"
  ],
  "compile_args": [
    "-std=c++20",
    "-IC:\\fake-dir1\\src",
    "-IC:\\fake-dir2\\include",
    "-IC:\\fake-dir3\\thirdparty\\include"
  ],
  "clear_all_blank_lines_inside_function": true,
  "cut_all_comments": true,
  "cut_all_comments_exception_substr_set": ["hesong", "Copyright"],
  "force_braces_for_single_statement_after_condition": true,
  "blank_lines_between_fucntion_and_any_object": 2
}

Sample file: clang-hesong.json.example

2. Key features (detailed)

2.1 naming_style

Main feature. Rewrites eligible C/C++ identifiers so they all follow one naming convention. Set in JSON, run on a file; change the value and run again to switch styles.

Same identifiers, three styles:

Example ("naming_style": "snake"):

// before
class MyWidget {
    void doSomething();
    int itemCount;
};

// after (eligible names in this file)
class my_widget {
    void do_something();
    int item_count;
};

Applies to: functions, methods, variables, parameters, class/struct/enum members, C++17 structured-binding names, types, typedef / using aliases, enum constants, identifiers inside #define bodies (when eligible). Does not change #includes, formatting, logic, or the program entry symbol main. Qualified type names after :: (e.g. nlohmann::json) are left unchanged.

Which symbols are renamed:

2.2 this_module_include_dirs

This does not mean “only rename symbols under these directories.”
It answers a different question: for a symbol used in the file you are formatting but declared in another file (an external symbol) — should that name be rewritten here to follow naming_style?

Rule: look at where the symbol is declared (its declaration header’s file path). If that path matches one of the directories in this_module_include_dirs, the symbol is treated as your module’s API and is renamed at use sites in the file being formatted (function calls, types, members, …). If the declaration comes from outside that set (third-party SDK, STL, other libs), the name is left unchanged.

Therefore: functions from other modules and the C/C++ standard library (e.g. std::vector, printf) are not wrongly renamed — their declaration headers are not under this_module_include_dirs, so calls to them in your file keep the original spelling.

Purpose: directory roots for your module’s headers. Used with naming_style to decide which external declarations count as module API.

Rule (matches should_rename_decl + apply_naming_style_to_ref in the bundled exe):

How “matches” works: is_this_module_header checks whether the declaration header’s absolute file path contains one of the configured directory strings (case-insensitive substring). List the roots where your API headers live — not third-party -I trees.

Do not list third-party or system header roots here. Put those paths only in compile_args -I so Clang can parse them. Listing them in this_module_include_dirs would mark foreign APIs as “yours” and break builds.

compile_args -I vs this_module_include_dirs — do not confuse them:

Example (placeholders):

"this_module_include_dirs": [
  "C:\\fake-dir1\\src",
  "C:\\fake-dir2\\include"
],
"compile_args": [
  "-std=c++20",
  "-IC:\\fake-dir1\\src",
  "-IC:\\fake-dir2\\include",
  "-IC:\\fake-dir3\\thirdparty\\include"
]

• fake-dir1 / fake-dir2 — your module header roots. A function declared in fake-dir2\\api\\foo.h and called from the .cpp you are formatting will be renamed with naming_style at the call site in that .cpp.
• fake-dir3\\thirdparty — in compile_args only (Clang needs the -I to parse #includes); not in this_module_include_dirs, so third-party names like SomeSdkFunction stay unchanged.

Rule of thumb: Every path in this_module_include_dirs should usually also have a matching -I in compile_args. The reverse is not true — many -I paths are third-party and belong only in compile_args.

Single-file mode (extension): only the file you run on is written to disk. Formatting a .cpp updates names in that .cpp; run again on each .h to update header declarations (or use CLI input_dir / output_dir).

2.3 compile_args

Clang flags for virtual compile — must mirror how your project builds the same .c / .cpp file so the AST can be built.

Does not need: -I for standard library (<vector>, <stdio.h>, …).

Copy -I and -D from CMake / MSBuild / your real build. On Windows JSON: "C:\\path".

2.4 Other parameters (brief)

Extension setting (VS Code settings.json, not in clang-hesong.json): clang-hesong.configPath — path to config file (default .vscode/clang-hesong.json).

JSON → exe argument mapping:

3. Quick start

1. Open Folder — open your C/C++ project as a VS Code workspace.
2. clang-hesong: Open Config — creates .vscode/clang-hesong.json; set "naming_style": "snake" (or "camel" / "pascal"), list your code roots in this_module_include_dirs, and replace C:\fake-dir1 placeholders in compile_args.
3. clang-hesong: Run On This File — right-click a saved .cpp / .c / .h (Explorer or editor), or Ctrl+Shift+P → clang-hesong.

Output: View → Output → clang-hesong (start/end timestamps per file).
Bugs: GitHub Issues

3.1 Back up first

⚠️ Run On This File overwrites the target on disk (rename, comments, braces, blank lines). Commit in git, copy the file, or test on a throwaway branch before batch runs.

3.2 How it works (Clang)

The tool compiles one file with your compile_args (-std, every project/third-party -I, -D macros). Clang must resolve all #includes — same rules as your real build. Standard-library headers do not need extra -I.

Licensing: extension JS is MIT; bundled exe includes LLVM/Clang (Apache-2.0 WITH LLVM-exception).

4. Commands

Run On This File only appears for C/C++ file extensions / language modes. If menus are missing: Reload Window and confirm extension clang-hesong is enabled.

4.1 Open Config — what you see

To reset: delete .vscode/clang-hesong.json, then Open Config again.

This is not clang-format, Prettier, or a generic text formatter. It does not preview changes — it overwrites the file immediately. C/C++ only (.c, .cpp, .h, …).

5. Troubleshooting

6. Third-party licenses

This extension is not affiliated with or endorsed by the LLVM Project.

When redistributing the .vsix or installed package, keep both LICENSE and THIRD_PARTY_NOTICES.md.

7. Reporting issues

Report bugs and feature requests on GitHub (not the Marketplace Q&A).

You need a free GitHub account to open an issue.

7.1 Steps

1. Open New issue: https://github.com/acidrainspace/clang-hesong-extension/issues/new/choose
2. Choose Bug report and fill in the form.
3. Fill in environment, steps, config, and Output → clang-hesong log.
4. Submit. We respond on GitHub; you can subscribe to email notifications on the thread.

7.2 What to include

Environment

• VS Code version: Help → About
• clang-hesong version: Extensions → clang-hesong (Publisher HeSong Tools)
• Windows version (x64)

What happened — what you did, expected vs actual behavior.

Steps to reproduce — numbered list.

Configuration — paste .vscode/clang-hesong.json (redact paths if needed).

Output log — View → Output → clang-hesong → copy full text from the failed run.

Sample file (optional) — minimal .cpp / .h or steps to reproduce on a snippet.

7.3 Before you report

• Check existing issues for duplicates.
• Parse / -I errors: confirm compile_args (see §2.3).
• Do not paste secrets into public issues.

8. Requirements

• C/C++ source files (see scope above)
• Windows x64
• VS Code 1.90+
• Valid compile_args: -std, all project/third-party -I paths, and any required -D macros (see §2.3)