注释是编程中仅次于“Hello, world!”的单词，通常是你在向世界问好之后学到的下一件事。它们通常有两种形式：单行注释和多行注释，例如//和/* */。它们的目的是解释当前的代码逻辑并提供注释。
什么是评论？
在深入探讨“为什么没有人再想写代码注释？”这个问题之前，让我们先看看人们实际上是如何写注释的。
例如，某些项目或编码标准要求在文件开头声明版权信息。这可能包括 ASCII 艺术或许可详细信息：
/*
* 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.
*/有些甚至包括 ASCII 艺术：
/*
* _oo0oo_
* o8888888o
* 88" . "88
* (| -_- |)
* 0\ = /0
* ___/`---'\___
* .' \\| |// '.
* / \\||| : |||// \
* / _||||| -:- |||||- \
* | | \\\ - /// | |
* | \_| ''\---/'' |_/ |
* \ .-\__ '-' ___/-. /
* ___'. .' /--.--\ `. .'___
* ."" '< `.___\_<|>_/___.' >' "".
* | | : `- \`.;`\ _ /`;.`/ - ` : | |
* \ \ `_. \_ __\ /__ _/ .-` / /
* =====`-.____`.___ \_____/___.-`___.-'=====
* `=---='
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* Buddha bless, never crashes, never bugs
*/在公司工作时，声明函数的作者是很常见的。如果函数有问题，更容易找到责任人（承担责任）：
/**
* Title base agent.<br>
* Description base agent.<br>
*
* @author yuanci.ytb
* @since 1.0.0-M2
*/一些 IDE 甚至会自动为您生成注释格式，例如 Laravel（或 Java 的 Spring 框架）：
/**
* 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;
}有时，注释用于禁用旧功能：
{
// image
}
{
/* {isValidImageIcon
? <img src={imageUrl} className="w-full h-full rounded-full" alt="answer icon" />
: (icon && icon !== '') ? <em-emoji id={icon} /> : <em-emoji id=' ' />
} */
}那么为什么没有人再想写代码注释了？
注释通常分为两类：一类解释信息，另一类注释功能。请考虑以下没有注释的代码 - 需要花费一些时间才能理解它的作用：
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;
}添加注释可以使其更容易理解：
// 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;
}人们宁愿事后花五分钟理清逻辑，也不愿在灵感迸发时花时间写评论。
我认为很大程度上是因为害怕以下几种情况：
怕有人会说：
“不就是求最长不重复子串的长度这个计算逻辑吗，小学的时候就学会了，你还写评论？你好弱啊。”
“这个人写了这么多评论，肯定是新手。”
“在你的代码中写注释？明天人工智能就会取代你！”
那么我们为什么不写评论呢？我认为 50% 的原因是纯粹的懒惰，另外 50% 是害怕这种情况。但是，当我们查看别人的项目时，我们希望他们的评论和文档尽可能详细——因为越详细越好。
随着 CSS 的发展，我们很多人都接触过 SASS、Less，这些扩展不可避免地需要数学运算（加减乘除）来实现复杂的效果，例如：
$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);
}偶尔出现这样的代码片段还好，但如果代码很长，你可能要花很多时间才能弄清楚，甚至调试它。考虑以下较长的代码片段：
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;
}许多人可能最终会去 MDN 寻找定义，比如 mask 的作用以及它在这里是如何使用的。
如果我们添加评论，我们可能会遭遇同样的嘲笑：
“不就是个面具吗？这个我小学就学过，你还写评论？你好弱啊。”
“这个人甚至为 CSS 写注释。肯定是新手。”
“写评论？明天AI就来代替你了！”
我们需要代码注释！
我们需要代码注释，但我们也需要控制哪些注释对其他人可见。许多插件可以隐藏注释，但如果您同时需要可见性和隐私性，则可以使用 comment-hide VSCode 插件。
它提供了两个命令：Save Comments和Restore Comments。前者提取并删除注释，并将其存储在.annotations/目录中，而后者恢复它们 — 前提是文件在此期间没有更改。
Windows/Linux 快捷方式：Ctrl+Shift+P
macOS 快捷方式：Cmd+Shift+P
例如：
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 运行之后Save Comments变成：
1 /* >>>
2 This will not be hidden and will be 3 visible to everyone
3 */
4
5 const x = 42;块/* */保留，因为 comment-hide 允许使用 保留注释>>>。只有块样式/* */注释支持此功能。
这些评论都存放在.annotations/根目录的文件夹中，你可以通过当前文件名来找到 JSON 文件。
{
"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"
}
要恢复注释，请运行Restore Comments，插件将根据行号和位置重新插入注释：
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 如果您添加.annotations/到.gitignore，其他人将看不到。只有>>>评论可见。
这个插件有什么缺点吗？
是的——此插件依赖绝对定位。如果您修改行号或缩进，恢复注释可能会变得不可靠。因此，最好Save Comments只在一切完成后才使用。
支持的评论样式
该插件支持四种主要的注释样式，涵盖多种语言：
// Hello
# Hello
/*
Hello
*/
<!-- Hello -->为什么不支持 Python 的'''和"""？开发人员很懒。
这四种风格涵盖了大多数现代语言，包括：
JavaScript - HTML - Markdown - CSS - C++ - C# - Java - Python - Golang - Rust - Ruby - JSX/TSX...安全问题
由于此插件需要读/写权限，有些人可能会担心代码隐私问题。幸运的是，它是开源的。您可以在此处查看源代码。该插件通过 GitHub Actions 发布，确保不会出现恶意代码注入或数据泄露。
README 包含有关其当前限制的 红色警告。未来的更新旨在允许一键隐藏/恢复整个项目并提高定位可靠性。
编码中的网络欺凌
归根结底，问题在于网络欺凌。如果你从未经历过，不妨想想《黑暗之魂 3》玩家的情况。
有些玩家对游戏不熟悉，在与无名之王这样的 Boss 战斗数小时后，便会放弃并求助于指南。而其他玩家则享受挑战和最终胜利带来的多巴胺冲动。
但有些开发人员以同样的方式阻止评论，让那些使用评论的人感到羞耻。阿尔伯特·爱因斯坦曾经说过：
“每个人都是天才。但如果你用爬树的能力来评判一条鱼，它会终其一生都相信自己很笨。”