代码注释的换行

matklad 2026/02/21 00:00 工具

code-comments line-wrapping editor-tips formatting programming developer-tools

摘要

本文认为代码和注释应分别换行到不同的列宽，注释的宽度应相对于注释起始位置而定，并讨论了当前编辑器工具对相对换行支持不足的问题。

<header> <h1>代码注释的换行</h1> <time class="meta" datetime="2026-02-21">2026年2月21日</time> </header> 直到今天我才意识到： <ul> <li> 代码和代码注释理想情况下应换行到不同的列宽。 </li> <li> 对于注释，宽度应相对于注释的起始位置。 </li> </ul> 将行长度限制在约100列是一个好主意。这是一个物理限制，即仍能舒适地将两个编辑器并排放置的宽度（见 <a href="https://matklad.github.io/2025/11/28/size-matters.html">尺寸很重要</a>）。注意一个明显的矛盾：可读性最佳的文章宽度通常较窄，为60–70列。这个矛盾可以通过注意到，对于代码，缩进会占用可用空间来解决。通常，代码的排版密度远低于文章。 尽管如此，我发现当注释块的换行宽度比周围代码更窄时，阅读起来更容易。我希望代码行在100列处换行，而注释的内容在70列处换行（除非这会使整行超过100列）。也就是说，我希望布局像这样（为了说明，使用20/30的标尺代替70/100）： <figure class="code-block"> <pre><code>// 顶层注释 // 可以这么宽。 const S = struct { // 嵌套注释 // 也是这么宽，但 // 向右缩进了。 fn f() void { switch (value) { 0 => { // 但存在 // 硬限制。 } } } }</code></pre> </figure> 这看起来事后来看很明显，但值得注意的是工具对此支持得并不好？我使用的 <a href="https://marketplace.visualstudio.com/items?itemName=stkb.rewrap">VS Code扩展</a>允许为注释配置专用的填充列，但不会使其相对，因此缩进的注释块总是比顶层注释块窄。Emacs 的 <code>M-q</code> 默认也不支持相对换行！ <hr> 关于硬换行的题外话：我们是否应该费心去换行注释？难道不能依靠编辑器来实现软换行吗？软换行的问题在于，如果不理解文本的含义，就无法正确地软换行。考虑一个 Markdown 列表： <figure class="code-block"> <pre><code>一个列表： * 项目一， * 项目二。</code></pre> </figure> 如果第一个项目长到需要换行，那么换行后的行也应该缩进，这就需要先将文本解析为 Markdown： <figure class="code-block"> <pre><code>一个列表： * 项目一长到需要 换行， * 项目二。</code></pre> </figure>

查看原文

查看缓存全文

缓存时间: 2026/05/16 03:34

# 代码注释的换行来源：https://matklad.github.io/2026/02/21/wrapping-code-comments.html 2026 年 2 月 21 日今天我幡然醒悟： - 代码和代码注释的理想换行宽度应该不同。 - 对于注释，换行宽度应该相对于注释起始位置。将行长度限制在大约 100 字符是个好主意。这是一个物理限制：在这个宽度下，你仍然可以舒服地在并排摆放两个编辑器（参见 *Size Matters* (https://matklad.github.io/2025/11/28/size-matters.html)）。注意一个明显的矛盾：可读性最佳的散文宽度通常更窄，在 60–70 字符之间。这个矛盾可以通过注意到以下事实来解决：对代码来说，缩进会侵占可用空间。通常情况下，代码的排版密度远低于散文。尽管如此，我发现当注释块换行比周围代码更窄时，它们更容易阅读。我希望行在 100 字符处换行，而*注释内容*在 70 字符处换行（除非这样会导致整行超过 100 字符）。也就是说，我希望布局如下（用 20/30 标尺代替 70/100 进行说明）： ``` // 顶层注释可以 // 有这么宽。 const S = struct { // 嵌套注释也 // 这么宽，但 // 向右偏移了。 fn f() void { switch (value) { 0 => { // 但这里 // 有硬限制。 } } } } ``` 事后看来这很明显，但工具似乎并没有很好地支持这一点？我用的 VS Code 扩展 (https://marketplace.visualstudio.com/items?itemName=stkb.rewrap) 允许为注释配置专用的填充列，但并没有使其*相对*，因此缩进的注释块总是比顶层注释块窄。Emacs 的 `M-q` 也无法开箱即用地实现相对换行。 --- 关于硬换行的题外话：我们到底要不要费心对注释进行换行？难道不能依赖编辑器实现软换行吗？软换行的问题在于，如果不知道文本的意义，就无法正确地软换行。考虑一个 markdown 列表： ``` A list: * item one, * item two. ``` 如果第一项长到需要换行，那么换行后的行也应该缩进，这需要先将文本解析为 markdown： ``` A list: * item one which is long enough necessitate wrapping, * item two. ```

代码注释的换行

相似文章

代码评审回复：在关键时刻添加上下文

The comments that go into code versus those that go into the pull request description

@the_smart_ape: https://x.com/the_smart_ape/status/2053034897514660074

非尾部分隔符并不令人愉悦

使用 Claude Code：HTML 的惊人效力

提交意见反馈