VSCode plugin comment-hide: Dare to write comments!

brights — Mon, 31 Mar 2025 13:03:49 +0000

Comments, second only to "Hello, world!" in programming, are usually the next thing you learn after greeting the world. They typically come in two forms: single-line comments and multi-line comments, such as // and /* */. Their purpose is to explain the current code logic and provide annotations.

What Are Comments?

Before diving into the question "Why Doesn't Anyone Want to Write Code comments Anymore?", let's first look at how people actually write comments.

For example, some projects or coding standards require declaring copyright information at the beginning of a file. This could include ASCII art or licensing details:

/*
 * Copyright 2024-2025 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

Some even include ASCII art:

/*
 *                        _oo0oo_
 *                       o8888888o
 *                       88" . "88
 *                       (| -_- |)
 *                       0\  =  /0
 *                     ___/`---'\___
 *                   .' \\|     |// '.
 *                  / \\|||  :  |||// \
 *                 / _||||| -:- |||||- \
 *                |   | \\\  - /// |   |
 *                | \_|  ''\---/''  |_/ |
 *                \  .-\__  '-'  ___/-. /
 *              ___'. .'  /--.--\  `. .'___
 *           ."" '<  `.___\_<|>_/___.' >' "".
 *          | | :  `- \`.;`\ _ /`;.`/ - ` : | |
 *          \  \ `_.   \_ __\ /__ _/   .-` /  /
 *      =====`-.____`.___ \_____/___.-`___.-'=====
 *                        `=---='
 *
 *      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 *
 *            Buddha bless, never crashes, never bugs
 */

When working at a company, it's common to declare the author of a function. If the function has issues, it's easier to find the person responsible (to take the blame):

/**
 * Title base agent.<br>
 * Description base agent.<br>
 *
 * @author yuanci.ytb
 * @since 1.0.0-M2
 */

Some IDEs even generate comment formats for you automatically, such as Laravel (or Java’s Spring framework):

/**
 * Create a new repository builder instance.
 *
 * @param \Dotenv\Repository\Adapter\ReaderInterface[] $readers
 * @param \Dotenv\Repository\Adapter\WriterInterface[] $writers
 * @param bool                                         $immutable
 * @param string[]|null                                $allowList
 *
 * @return void
 */
private function __construct(array $readers = [], array $writers = [], bool $immutable = false, ?array $allowList = null)
{
    $this->readers = $readers;
    $this->writers = $writers;
    $this->immutable = $immutable;
    $this->allowList = $allowList;
}

Sometimes, comments are used to disable old functionality:

{
  // image
}
{
  /* {isValidImageIcon
      ? <img src={imageUrl} className="w-full h-full rounded-full" alt="answer icon" />
      : (icon && icon !== '') ? <em-emoji id={icon} /> : <em-emoji id='🤖' />
    } */
}

So Why Doesn't Anyone Want to Write Code comments Anymore?

Comments generally fall into two categories: one explains information, and the other annotates functionality. Consider the following code without comments—it takes time to understand what it does:

function lengthOfLongestSubstring(s) {
  let charIndexMap = new Map(),
    longest = 0,
    left = 0;

  for (let right = 0; right < s.length; right++) {
    if (charIndexMap.has(s[right]) && charIndexMap.get(s[right]) >= left) {
      left = charIndexMap.get(s[right]) + 1;
    }
    charIndexMap.set(s[right], right);
    longest = Math.max(longest, right - left + 1);
  }
  return longest;
}

Adding comments makes it easier to understand:

// Computes the length of the longest substring without repeating characters
function lengthOfLongestSubstring(s) {
  let charIndexMap = new Map(),
    longest = 0,
    left = 0;

  for (let right = 0; right < s.length; right++) {
    // If the character exists in the map and its index is >= left pointer, move left pointer
    if (charIndexMap.has(s[right]) && charIndexMap.get(s[right]) >= left) {
      left = charIndexMap.get(s[right]) + 1;
    }
    // Update the character's latest index in the map
    charIndexMap.set(s[right], right);
    // Update the longest substring length
    longest = Math.max(longest, right - left + 1);
  }
  return longest;
}

People would rather spend five minutes sorting out the logic later than take the time to write comments when inspiration strikes.

I think it's largely because of the fear of the following situations:

Afraid someone might say:

"Isn't it just a calculation logic for finding the length of the longest substring without repeating characters? I could do that in elementary school. You wrote a comment for this? You're so weak."

"This person writes so many comments, they must be a newbie."

"Writing comments in your code? AI will replace you tomorrow!"

So why don’t we write comments? I think 50% of the reason is pure laziness, and the other 50% is the fear of situations like these. However, when we look at someone else's project, we hope their comments and documentation are as detailed as possible—because the more detailed, the better.

With the development of CSS, many of us have encountered SASS and Less. These extensions inevitably require mathematical operations (addition, subtraction, multiplication, division) to achieve complex effects. For example:

$padding: 12px;

.post {
  // Since these max() calls are valid calculation expressions, they're
  // parsed as calculations.
  padding-left: max($padding, env(safe-area-inset-left));
  padding-right: max($padding, env(safe-area-inset-right));
}

.sidebar {
  // Since these use the SassScript-only modulo operator, they're parsed as
  // SassScript function calls.
  padding-left: max($padding % 10, 20px);
  padding-right: max($padding % 10, 20px);
}

A snippet like this is fine once in a while, but if there's a long chunk of code, you might spend a lot of time figuring it out—or even debugging it. Consider the following long segment:

body::before {
    --size: 45px;
    --line: color-mix(in hsl, canvasText, transparent 70%);
    content: '';
    height: 100vh;
    width: 100vw;
    position: fixed;
    background: linear-gradient(
          90deg,
          var(--line) 1px,
          transparent 1px var(--size)
        )
        50% 50% / var(--size) var(--size),
      linear-gradient(var(--line) 1px, transparent 1px var(--size)) 50% 50% /
        var(--size) var(--size);
    mask: linear-gradient(-20deg, transparent 50%, white);
    top: 0;
    transform-style: flat;
    pointer-events: none;
    z-index: -1;
  }

Many people might end up checking MDN for definitions, such as what mask does and how it's being used here.

If we add comments, we risk encountering the same ridicule:

"Isn't it just a mask? I learned this in elementary school. You wrote a comment for this? You're so weak."

"This person writes comments even for CSS. Must be a newbie."

"Writing comments? AI will replace you tomorrow!"

We need Code comments!

We need Code comments, but we also need to control which comments are visible to others. Many plugins can hide comments, but if you need both visibility and privacy, you can use the comment-hide VSCode plugin.

It provides two commands: Save Comments and Restore Comments. The former extracts and removes comments, storing them in the .annotations/ directory, while the latter restores them—provided the file hasn't changed in the meantime.

Windows/Linux shortcut: Ctrl+Shift+P
macOS shortcut: Cmd+Shift+P

For example:

0 /* >>>                                                               
1   This will not be hidden and will be 2 visible to everyone          
2 */                                                                   
3                                                                      
4 const x = 42; // This is a comment                                   
5 /* This is a multi-line                                              
6    comment */                                                        
7 // Another comment

After running Save Comments, it becomes:

1 /* >>>                                                           
2   This will not be hidden and will be 3 visible to everyone      
3 */                                                               
4                                                                  
5 const x = 42;

The /* */ block remains because comment-hide allows preserving comments using >>>. Only block-style /* */ comments support this feature.

These comments are stored in the .annotations/ folder at the root directory. You can locate the JSON file by following the current file name.

{
  "originalContent": "/* >>>\n  This will not be hidden and will be visible to everyone\n*/\n\nconst x = 42; // This is a comment\n/* This is a multi-line\n   comment */\n// Another comment",
  "comments": [
    {
      "text": "// This is a comment",
      "line": 4,
      "start": 83,
      "end": 103
    },
    {
      "text": "/* This is a multi-line\n   comment */",
      "line": 5,
      "start": 104,
      "end": 141
    },
    {
      "text": "// Another comment",
      "line": 7,
      "start": 142,
      "end": 160
    }
  ],
  "filePath": "test/hhha.js"
}

To restore comments, run Restore Comments, and the plugin will reinsert comments based on line numbers and positions:

0 /* >>>                                                               
1   This will not be hidden and will be 2 visible to everyone          
2 */                                                                   
3                                                                      
4 const x = 42; // This is a comment                                   
5 /* This is a multi-line                                              
6    comment */                                                        
7 // Another comment

If you add .annotations/ to .gitignore, others won’t see it. Only >>> comments will remain visible.

Are There Any Drawbacks to This Plugin?

Yes—this plugin relies on absolute positioning. If you modify line numbers or indentation, restoring comments may become unreliable. Therefore, it's best to use Save Comments only when everything is finalized.

Supported Comment Styles

The plugin supports four major comment styles, covering many languages:

// Hello

# Hello

/*
  Hello
*/

<!-- Hello -->

Why not support Python’s ''' and """ ? The developer was lazy.

These four styles cover most modern languages, including:

JavaScript - HTML - Markdown - CSS - C++ - C# - Java - Python - Golang - Rust - Ruby - JSX/TSX...

Security Concerns

Since this plugin requires read/write access, some may worry about code privacy. Fortunately, it's open-source. You can view the source code here. The plugin is published via GitHub Actions, ensuring no malicious code injection or data leaks.

The README contains a 🟥 red warning about its current limitations. Future updates aim to allow one-click hiding/restoring for entire projects and improve positioning reliability.

Cyberbullying in Coding

At the end of the day, the problem is cyberbullying. If you’ve never experienced it, consider the case of Dark Souls 3 players.

Some players, unfamiliar with the game, struggle for hours against a boss like the Nameless King before giving up and turning to guides. Others enjoy the challenge and the eventual dopamine rush of victory.

But some developers discourage comments in the same way, shaming those who use them. Albert Einstein once said:

"Everybody is a genius. But if you judge a fish by its ability to climb a tree, it will live its whole life believing that it is stupid."

(Or maybe he didn’t say it—but hey, you’re not going to fact-check, are you?)

DEV Community: brights