clang-hesong

VS Code extension that bundles clang-format-hesong.exe and rewrites C/C++ source files in place using a workspace JSON config.

C/C++ only · powered by Clang AST

Language scope C and C++ only — not Python, Java, C#, Rust, JavaScript, etc.

Supported files .c, .cc, .cpp, .cxx, .h, .hh, .hpp, .hxx

How it works The bundled tool is built on LLVM/Clang. It parses your file into a Clang AST, then applies rewrites from that tree. Your config compile_args must supply -std, every -I needed for project/third-party headers (direct and indirect; stdlib excluded), and any -D macros — otherwise Clang cannot parse the file and the run fails.

Platform Windows x64 only (v1). The native exe is pre-built and included — no MSVC/LLVM install on your machine.

If Clang cannot parse a file (wrong include paths, unsupported constructs, etc.), results may be incomplete or the run may fail. This is not a generic text formatter.

Licensing: The JavaScript extension is MIT. The bundled clang-format-hesong.exe includes LLVM/Clang libraries (Apache-2.0 WITH LLVM-exception). This is not an official LLVM Project extension.

Windows only. No build tools required on your machine — the native exe is pre-built and included.

⚠️ Back up your source files first

clang-hesong rewrites the target file in place. There is no preview step and no automatic undo inside the extension. Running clang-hesong: Run On This File overwrites the file on disk immediately (rename identifiers, strip comments, adjust braces/blank lines, etc.).

Before you run the tool:

Commit your changes in git, or

Copy the file(s) you plan to transform, or

Rely on VS Code Local History / your editor undo only if the file is still open and unchanged since the run — do not treat undo as a safe backup.

Test on a single file or a throwaway branch until you trust your .vscode/clang-hesong.json settings.

Commands

Command	Description
clang-hesong: Open Config	Create or open `.vscode/clang-hesong.json`
clang-hesong: Run On This File	Format the right-clicked or focused source file in place

Right-click any .c / .cpp / .h file in the Explorer or editor.

Quick start

Install this extension from the Marketplace.
Open a C/C++ workspace.
Run clang-hesong: Open Config to create .vscode/clang-hesong.json.
Edit paths and compile_args for your project.
Right-click a source file → clang-hesong: Run On This File.

The file is rewritten in place (see warning above). On failure, check the clang-hesong output channel (View → Output → clang-hesong).

Configuration

Extension setting (optional)

Default config path is .vscode/clang-hesong.json. Override in settings.json:

{
  "clang-hesong.configPath": ".vscode/clang-hesong.json"
}

Tool config (required)

Example .vscode/clang-hesong.json:

{
  "naming_style": "snake",
  "this_module_include_dirs": [
    "C:\\my-project\\src"
  ],
  "clear_all_blank_lines_inside_function": true,
  "cut_all_comments": true,
  "cut_all_comments_exception_substr_set": ["hesong"],
  "force_braces_for_single_statement_after_condition": true,
  "blank_lines_between_fucntion_and_any_object": 2,
  "compile_args": [
    "-std=c++20",
    "-IC:\\my-project\\src",
    "-IC:\\my-project\\include"
  ]
}

Config keys

Summary (details below):

Key	Required	Type	Default	What it does
`naming_style`	Yes	`snake` \| `camel` \| `pascal`	—	Rename identifiers in your module to the target convention
`compile_args`	Yes	string[]	—	Clang parse flags; must list every project/third-party `-I` path (stdlib paths not needed)
`this_module_include_dirs`	No	string[]	omitted	Directories that define your code; limits renaming scope
`clear_all_blank_lines_inside_function`	No	boolean	`false`	Collapse extra blank lines inside `{ ... }` function bodies
`cut_all_comments`	No	boolean	`false`	Strip almost all comments after rewriting (see exception list)
`cut_all_comments_exception_substr_set`	No	string[]	omitted	When `cut_all_comments` is on: only keep comments whose text contains a listed substring; all other comments are deleted
`force_braces_for_single_statement_after_condition`	No	boolean	`false`	Wrap single-statement `if` / `for` / `while` bodies in `{ }`
`blank_lines_between_fucntion_and_any_object`	No	integer	`-1` (off)	Fix blank-line count between top-level declarations

The extension sets input_output_file automatically. Do not add input_dir / output_dir to the JSON.

`naming_style` (required)

Semantics: Target naming convention for identifiers that belong to your module (see this_module_include_dirs). The tool parses the file with Clang, walks the AST, and renames symbols such as functions, methods, variables, parameters, members, and type names declared in your module.

Values: snake (e.g. camelCase → camel_case), camel, pascal. Macro bodies get a separate text-based pass after the AST rewrite.

`compile_args` (required)

Semantics: Flags passed to Clang’s virtual compile so the tool can parse your file and build an AST. These are not used to build the formatter — they should mirror how your project compiles the same .cpp / .c file.

⚠️ -I must cover all non–standard-library headers

compile_args must include -I paths for every directory that supplies headers your source needs — directly or indirectly — except standard library headers.

Include type Need -I? Example

Your project headers Yes -IC:\my-project\src, -IC:\my-project\include

Third-party / vendored headers Yes -IC:\my-project\thirdparty\foo\include

Transitive headers (A includes B includes C) Yes — every level If foo.h pulls in bar/baz.h, the -I that finds bar/ must be listed

C/C++ standard library (<vector>, <stdio.h>, …) No Clang already knows system include paths for the chosen -std

Why: The bundled tool does not guess your project layout. It runs Clang on one file as a translation unit: Clang follows #include and must open each header file on disk. If a project or third-party header path is missing from -I, Clang reports file not found, parsing stops, and the run fails (non-zero exit) or produces unreliable output.

Practical rule: Copy the same -I (and -D) flags you use in CMake/msbuild/your real build for that target. When in doubt, add another -I rather than omit one.

Typical entries:

Flag	Purpose
`-std=c++17` / `-std=c++20`	Language standard (also selects correct stdlib headers)
`-IC:\path\to\include`	Project and third-party header search paths
`-DNAME=value`	Macros your headers/source depend on
`-Wno-...`	Optional: suppress parse noise

"compile_args": [
  "-std=c++20",
  "-IC:\\my-project\\src",
  "-IC:\\my-project\\include",
  "-IC:\\my-project\\thirdparty\\foo\\include"
]

On Windows, use escaped backslashes or forward slashes in JSON.

`this_module_include_dirs` (optional)

Semantics: Directories that mark your code. Only symbols from headers under these paths are renamed; system and third-party headers are left unchanged. Recommended for all real projects.

`clear_all_blank_lines_inside_function` (optional)

Semantics: Removes extra blank lines inside function bodies. Does not affect spacing between top-level functions. Default: false.

`cut_all_comments` (optional)

Semantics: After AST rewriting, removes comments from the generated source in a text post-pass. Default: false.

Typical use: AI-assisted coding often leaves large volumes of low-value comments (“this function initializes…”, restated obvious logic, boilerplate doc blocks). Turning this on clears that noise so the file reads like normal hand-written code.

Requires cut_all_comments: true before cut_all_comments_exception_substr_set has any effect.

`cut_all_comments_exception_substr_set` (optional)

Requires: cut_all_comments: true

Rule (read carefully):

When cut_all_comments is on, every // and /* */ comment is removed by default.
Exception: a comment is kept only if its full text contains at least one substring from this list (case-sensitive, anywhere in the line/block).
Comments that do not match any substring → deleted.

Why this exists: You usually want to wipe AI-generated clutter without losing a few comments you care about — license headers ("Copyright"), your own tags ("hesong"), TODO markers, etc. Put those marker words here; everything else goes.

Example:

"cut_all_comments": true,
"cut_all_comments_exception_substr_set": ["hesong", "Copyright", "TODO"]

Comment in source	Kept?	Reason
`// Initialize the widget`	❌ Removed	No substring match — typical AI filler
`// This loop iterates over all items`	❌ Removed	No match
`// hesong: do not rename this block`	✅ Kept	Contains `hesong`
`/* Copyright (c) 2026 My Corp */`	✅ Kept	Contains `Copyright`
`// TODO: fix edge case`	✅ Kept	Contains `TODO`

If cut_all_comments_exception_substr_set is omitted or empty while cut_all_comments is true, all comments are removed — no exceptions.

`force_braces_for_single_statement_after_condition` (optional)

Semantics: Wraps unbraced single-statement bodies of if / for / while / etc. in { }. Default: false.

`blank_lines_between_fucntion_and_any_object` (optional)

Spelling: Key is fucntion (historical typo) — must match exactly.

Semantics: Sets blank lines between top-level declarations (-1 or omit = off, 0 = none, 2 = exactly two blank lines between functions/classes/globals, etc.).

JSON → exe argument mapping

JSON key	Exe argument
`naming_style`	`naming_style=snake`
`compile_args`	one `compile_arg=...` per array element
`this_module_include_dirs`	`this_module_include_dirs={dir1,dir2}`
`clear_all_blank_lines_inside_function`	`clear_all_blank_lines_inside_function=true`
`cut_all_comments`	`cut_all_comments=true`
`cut_all_comments_exception_substr_set`	`cut_all_comments_exception_substr_set={a,b}`
`force_braces_for_single_statement_after_condition`	`force_braces_for_single_statement_after_condition=true`
`blank_lines_between_fucntion_and_any_object`	`blank_lines_between_fucntion_and_any_object=2`

Sample config in this repo: clang-hesong.json.example — copy to your workspace as .vscode/clang-hesong.json.

Troubleshooting

Symptom	Fix
`Config must contain naming_style`	Add `"naming_style": "snake"`
`compile_args array` error	Add at least one `-std` and `-I` flag
`Bundled exe not found`	Reinstall extension; verify `bin/win32-x64/clang-format-hesong.exe` exists
`No saved file is selected`	Save the file, then right-click it
Parse errors / run failed / `file not found` in output	Missing `-I` for a direct or indirect project/third-party header	Add all include dirs from your real build (not stdlib). Every header in the `#include` chain must resolve.
Parse errors in output (other)	Missing `-D` macros or wrong `-std`	Match your project’s compile flags
Third-party symbols renamed	Fix `this_module_include_dirs` to your module roots only
Windows only error	This extension requires Windows x64

Third-party licenses

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

Part	License
VS Code extension (`extension.js`, docs)	MIT — LICENSE
Bundled `clang-format-hesong.exe` (LLVM/Clang AST)	Apache-2.0 WITH LLVM-exception — THIRD_PARTY_NOTICES.md

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

Reporting issues

Bug reports and feature requests: GitHub Issues

Please include:

VS Code version (Help → About)
Windows version
Your .vscode/clang-hesong.json (redact paths if needed)
Full log from Output → clang-hesong
A minimal .cpp / .h sample and steps to reproduce, if possible

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 compile_args)

clang-hesong

hesong-tools

clang-hesong

C/C++ only · powered by Clang AST

⚠️ Back up your source files first

Commands

Quick start

Configuration

Extension setting (optional)

Tool config (required)

Config keys

`naming_style` (required)

`compile_args` (required)

⚠️ `-I` must cover all non–standard-library headers

`this_module_include_dirs` (optional)

`clear_all_blank_lines_inside_function` (optional)

`cut_all_comments` (optional)

`cut_all_comments_exception_substr_set` (optional)

`force_braces_for_single_statement_after_condition` (optional)

`blank_lines_between_fucntion_and_any_object` (optional)

JSON → exe argument mapping

Troubleshooting

Third-party licenses

Reporting issues

Requirements

clang-hesong

hesong-tools

clang-hesong

C/C++ only · powered by Clang AST

⚠️ Back up your source files first

Commands

Quick start

Configuration

Extension setting (optional)

Tool config (required)

Config keys

naming_style (required)

compile_args (required)

⚠️ -I must cover all non–standard-library headers

this_module_include_dirs (optional)

clear_all_blank_lines_inside_function (optional)

cut_all_comments (optional)

cut_all_comments_exception_substr_set (optional)

force_braces_for_single_statement_after_condition (optional)

blank_lines_between_fucntion_and_any_object (optional)

JSON → exe argument mapping

Troubleshooting

Third-party licenses

Reporting issues

Requirements

`naming_style` (required)

`compile_args` (required)

⚠️ `-I` must cover all non–standard-library headers

`this_module_include_dirs` (optional)

`clear_all_blank_lines_inside_function` (optional)

`cut_all_comments` (optional)

`cut_all_comments_exception_substr_set` (optional)

`force_braces_for_single_statement_after_condition` (optional)

`blank_lines_between_fucntion_and_any_object` (optional)