DEV Community

Sean Maxwell
Sean Maxwell

Posted on

I got tired of lining up comment dividers by hand, so I automated it

#javascript #typescript #showdev #productivity

This is a personal preference thing, but I like to write code top-down. Because of the way hoisting works in TypeScript/JavaScript, I can put the high-level stuff first and the details further down, so I split most files into regions in the same order every time:

Constants → Types → Classes (if any) → Functions → Export

To keep those regions easy to spot when I'm scrolling, I mark them with dividers like these:

// ========================================================================= //
//                                 CONSTANTS                                 //
// ========================================================================= //

const MAX_RETRIES = 3;

// ========================================================================= //
//                                 FUNCTIONS                                 //
// ========================================================================= //

// ============================= Shared Helpers ============================ //
Enter fullscreen mode Exit fullscreen mode

Big three-line headers for regions, and a single line for smaller sections inside a region.

The annoying part

Writing these by hand is tedious. Every label is a different length, so every header needs a different amount of = on each side to stay centered and end at the same column. I was copying and pasting old dividers, then deleting and adding = until the closing // lined up again.

I first wrote a small script for myself that ran when I hit save. Then I needed it on my work computer, then in another project, then for a Python file. Instead of copy-pasting the script everywhere, I turned it into an npm package: code-divider.

How it works

You write a marker on its own line:

// @reg constants

const MAX_RETRIES = 3;

// @reg functions

// @sec shared helpers
Enter fullscreen mode Exit fullscreen mode

Then run:

npx code-divider
Enter fullscreen mode Exit fullscreen mode

The markers are replaced in place with the headers from the top of this post. @reg creates a region, and @sec creates a section. By default, region labels become UPPERCASE and section labels become Capitalized Words, and every line ends at column 79.

code-divider inserting two region headers and a section header

With no options it processes the current directory recursively. It skips things like node_modules, dist, and .json files by default. You can also point it at one file or folder:

npx code-divider --path ./src/index.ts
Enter fullscreen mode Exit fullscreen mode

Add --dry-run to see which files would change without touching anything.

Run it on save

This is how I actually use it. I write a marker, hit save, and the header appears.

In VS Code, install the Run on Save extension and add this to your settings.json:

{
  "emeraldwalk.runonsave": {
    "commands": [
      {
        "match": "\\.(css|js|jsx|ts|tsx)$",
        "cmd": "npx code-divider"
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Any editor that can run a command on save works the same way.

"Why not just use snippets?"

Someone asked me this after my first post, and it's a fair question. Snippets can insert a header template, and if you're happy with that, keep using them. The catch is that snippets can change a label's case, but they can't count its characters. The filler stays the same length, so the line gets longer as the label gets longer:

// ================================= Helpers ================================= //
// ================================= Shared Helpers ================================= //
Enter fullscreen mode Exit fullscreen mode

code-divider sizes the filler around each label, so every header ends at the same column. It also works in any editor, or in CI.

Other languages

It isn't just for JavaScript. It ships with support for TypeScript, Java, CSS, SCSS, C, C++, Go, Rust, PHP, Ruby, Python, Bash, and SQL, and it uses each language's comment syntax:

# @sec helpers
Enter fullscreen mode Exit fullscreen mode

becomes

# ================================= Helpers ================================= #
Enter fullscreen mode Exit fullscreen mode

To change the defaults, generate a config file:

npx code-divider --init
Enter fullscreen mode Exit fullscreen mode

That writes a code-divider.config.json with every default setting. You only need to keep the settings you want to change. For example, wider headers with - as the filler:

{
  "All": {
    "CharacterLimit": 100,
    "FillerCharacter": "-"
  }
}
Enter fullscreen mode Exit fullscreen mode

You can also give a language its own settings, or add a language that isn't built in by giving it file extensions and a comment syntax.

Using it in CI

--check works like --dry-run, but exits with code 1 if any file would change. I use it to catch markers I forgot to format before they get committed:

npx code-divider --check
Enter fullscreen mode Exit fullscreen mode

Why I bother

If you don't like dividing code this way, that's fine, and this tool isn't for you. But I find that clearly separated regions make files faster to scan, both for me and for teammates reading my code. I've also found that AI coding tools seem to do better with files that are organized into obvious sections.

If you try it, I'd love to hear what you think. Bug reports, feature requests, and new language configs are all welcome.

Top comments (1)

Collapse
 
launchgatecheck profile image
Launch Gate •

The --check mode makes this practical in CI, not just on-save. One edge case worth a regression test: running the formatter twice should produce exactly the same bytes, especially if a label is wider than CharacterLimit or contains wide Unicode characters. A non-idempotent formatter in a save hook can create noisy diffs that are hard to spot in reviews.