Comment Bars

Features

Comment Bars, in the context of this extension, are comments in your code that help to separate your work into logical sections. Here are some Comment Bars using C-style comments:

Plain separator, no text:

/* ====================================================== */
/* ====================================================== */
/* ====================================================== */

Same as above, with added text:

/* ====================================================== */
/* ================== Comment Bars Rock ================= */
/* ====================================================== */

Want to customize width, dash (fill) character or thickness? No problem!

/* -------- Thinner ------- */

The Comment Bars extension automatically generates these separators.

Seamless Filling

When seamless filling is enabled, the Comment Bars extension will attempt to remove spaces between the comment delimeters and the fill characters. This ONLY happens if the bordering character of the delimeters is the same character as the fill character. Take a look at some examples.

The following examples were generated by the plugin, with a Python source code file active. Python uses the # symbol to start single line comments. As a result, these examples are applicaple to any syntax with a similar comment format. Lets get to it!

Python comment bar without seamless filling:

# ######################################################## #
# ##################### Not Seamless ##################### #
# ######################################################## #

Notice the spaces after the starting # symbol and before the ending # symbol, on each line.

Lets try that again, this time with seamless filling:

############################################################
######################### Seamless #########################
############################################################

Now those spaces are gone! Magic!

Lets change the fill character from the last example (still with seamless filling turned on):

# ======================================================== #
# ======================= Seamless? ====================== #
# ======================================================== #

Notice that the spaces between the comment delimeters and the fill characters come back now. This is the intended operation of seamless filling.

Activating Seamless Filling

At the moment, seamless filling is only available by using quick presets.

Terminology

In order to use this extension there are a few terms that you should be aware of.

• fill character — A single character of text that is repeated across the entire width of the comment bar.

• comment delimter — The string of code that a programming language looks for to indicate the beginning or end of a comment.

Commands and Instructions

• commentbars.generateAdvanced — labeled "Comment Bars: Generate (Advanced)" in Command Palette. Generate a comment bar using Advanced mode.

  Command Instructions:

  1. If you wish for your comment bar to contain text, type the text on an empty line and select it. Otherwise move the cursor to the empty line where you wish to insert the comment bar.
  2. Open the Command Palette: Ctrl+Shift+P on Windows and Linux, Cmd+Shift+P on Mac
  3. Find and run the command called Comment Bars: Generate (Advanced)
  4. Enter the the requested information in the boxes that pop up at the top of the editor.

• commentbars.generateQuick — labeled "Comment Bars: Generate (Quick)" in Command Palette. Generate a comment bar using a preset style (Quick mode).

  Command Instructions:

  1. If you wish for your comment bar to contain text, type the text on an empty line and select it. Otherwise move the cursor to the empty line where you wish to insert the comment bar.
  2. Open the Command Palette: Ctrl+Shift+P on Windows and Linux, Cmd+Shift+P on Mac
  3. Find and run the command called Comment Bars: Generate (Quick)
  4. Select the appropriate comment bar preset style from the list.

     Tip
     The presets can be customized with the commentbars.quickPresets setting.

Settings

This extension is highly configurable. The following lists the available settings for customizing the plugin:

• commentbars.defaultFillChar (see Terminology) — The default fill character. At the moment this is currently only used by the Advanced mode since quickPresets requires a fill character to be specified. Must be a string with a length of 1.

• commentbars.quickPresets — The available preset styles for Quick mode. Must be an array of objects. Each object accepts the following keys:

  • label — The name of the preset to display in the selection menu

  • fillChar — The fill character to use when this preset style is selected

  • width — The width of comment bars created using this preset style

  • thickness — The number of lines tall the comment bar will be, when using this preset style. This value will be rounded up to the nearest odd number in order to keep the text centered vertically.

  • seamlessFill (see Seamless Filling) — Optional, Enable seamless filling? Must be a bool (Default: false)

• commentbars.commentDelimsUser (see Comment Delimters) — The set of comment delimeters that is meant to be overridden by the user, or in workspace settings. The default value is empty.

• commentbars.commentDelimsFallback (see Comment Delimeters) — The global set of comment delimeters. The default value contains delimeters for most languages VSCode has built-in support for.

Advanced Configuration

Comment Delimeter Settings

There are currently two settings that can be customized to alter the comment delimters used by this extension:

• commentbars.commentDelimsUser
• commentbars.commentDelimsFallback

To make things easier they will be referred to as simply commentDelimsUser and commentDelimsFallback, for the rest of this section.

Both of these settings share the same format, which is described below.

Delimeter configurations must be an object in the following format (Documentation formatting loosely based on MSON):

• object[languageId (string)] — languageId is the key of the object. Each key should be a Visual Studio Code language identifier. See Language Id in VSCode documentation for more.a

  • (object) — Value corresponding to each languageId key above

    Properties:

    • start (string, required) — The start comment delimeter for the language with the id languageId. As an example, if you are trying to configure Comment Bars for a programming language that uses single line comments, starting with the # character. You could simply this option to the string, "#".

    • end (string, nullable) — The ending comment delimeter for the language with the id languageId. For instance, C-Style comments ( i.e. comments that look like /* */) require this to be set, for the */ portion. The default value of commentbars.commentDelimsFallback uses this option for many languages that don't need it, in order to make the comment bars symmetrical. If you do not like this you can override these languages in commentbars.commentDelimsUser.

Default Comment Delimeters

The default comment delimeters for most languages in Comment bars use single line comments. In these cases, the start delimeter is repeated as the end delimeter for symmetry.

Known Issues

If you spot any bugs, please open a new issue at this extension's GitHub repository!

The following is a list of all major issues with the Comment Bars extension:

• There are no known issues at this time

Release Notes

See the changelog in this extension's GitHub repository.

Happy Coding!