Wrapping Code Comments
Summary
The article argues that code and comments should be wrapped to different columns, with comment width relative to the comment start, and discusses how current editor tools don't properly support relative wrapping.
<header>
<h1>Wrapping Code Comments</h1>
<time class="meta" datetime="2026-02-21">Feb 21, 2026</time>
</header>
<p>I was today years old when I realized that:</p>
<ul>
<li>
Code and code comments ideally should be wrapped to a different column.
</li>
<li>
For comments, the width should be relative to the start of the comment.
</li>
</ul>
<p>It’s a good idea to limit line length to about 100 columns. This is a physical limit, the width at
which you can still comfortably fit two editors side by side (see
<a href="https://matklad.github.io/2025/11/28/size-matters.html"><em>Size Matters</em></a>). Note an apparent
contradiction: the optimal width for readable prose is usually taken to be narrower, 60–70 columns.
The contradiction is resolved by noticing that, for code, indentation eats into usable space.
Typically, code is much less typographically dense than prose.</p>
<p>Still, I find comment blocks easier to read when they are wrapped narrower than the surrounding
code. I want lines to be wrapped at 100, and <em>content</em> of comments to be wrapped at 70 (unless that
pushes overall line to be longer than 100). That is, I want layout like this (using 20/30 rulers
instead of 70/100, for illustrative purposes):</p>
<figure class="code-block">
<pre><code><span class="line"><span class="hl-comment">// Top level comments</span></span>
<span class="line"><span class="hl-comment">// can be this wide.</span></span>
<span class="line"><span class="hl-keyword">const</span> S = <span class="hl-keyword">struct</span> {</span>
<span class="line"> <span class="hl-comment">// Nested comments are</span></span>
<span class="line"> <span class="hl-comment">// also this wide, but</span></span>
<span class="line"> <span class="hl-comment">// are shifted right.</span></span>
<span class="line"> <span class="hl-keyword">fn</span><span class="hl-function"> f</span>() <span class="hl-type">void</span> {</span>
<span class="line"> <span class="hl-keyword">switch</span> (value) {</span>
<span class="line"> <span class="hl-numbers">0</span> => {</span>
<span class="line"> <span class="hl-comment">// But there is</span></span>
<span class="line"> <span class="hl-comment">// a hard limit.</span></span>
<span class="line"> }</span>
<span class="line"> }</span>
<span class="line"> }</span>
<span class="line">}</span></code></pre>
</figure>
<p>This feels obvious in retrospect, but notably isn’t be well-supported by the tools? The
<a href="https://marketplace.visualstudio.com/items?itemName=stkb.rewrap">VS Code extension</a> I use allows
configuring dedicated fill column for comments, but doesn’t make it <em>relative</em>, so indented comment
blocks are always narrower than top-level ones. Emacs <code>M-q</code> also doesn’t do relative wrapping out of
the box!</p>
<hr>
<p>Aside on hard-wrapping: should we bother with wrapping comments at all? Can’t we rely on our editor
to implement soft-wrapping? The problem with soft-wrapping is that you can’t soft-wrap text
correctly without understanding its meaning. Consider a markdown list:</p>
<figure class="code-block">
<pre><code><span class="line">A list:</span>
<span class="line"> * item one,</span>
<span class="line"> * item two.</span></code></pre>
</figure>
<p>If the first item is long enough to necessitate wrapping, the wrapped line should also be indented,
which requires parsing the text as markdown first:</p>
<figure class="code-block">
<pre><code><span class="line">A list:</span>
<span class="line"> * item one which is long enough</span>
<span class="line"> necessitate wrapping,</span>
<span class="line"> * item two.</span></code></pre>
</figure>
View Cached Full Text
Cached at: 05/16/26, 03:34 AM
# Wrapping Code Comments
Source: [https://matklad.github.io/2026/02/21/wrapping-code-comments.html](https://matklad.github.io/2026/02/21/wrapping-code-comments.html)
Feb 21, 2026I was today years old when I realized that:
- Code and code comments ideally should be wrapped to a different column\.
- For comments, the width should be relative to the start of the comment\.
It’s a good idea to limit line length to about 100 columns\. This is a physical limit, the width at which you can still comfortably fit two editors side by side \(see[*Size Matters*](https://matklad.github.io/2025/11/28/size-matters.html)\)\. Note an apparent contradiction: the optimal width for readable prose is usually taken to be narrower, 60–70 columns\. The contradiction is resolved by noticing that, for code, indentation eats into usable space\. Typically, code is much less typographically dense than prose\.
Still, I find comment blocks easier to read when they are wrapped narrower than the surrounding code\. I want lines to be wrapped at 100, and*content*of comments to be wrapped at 70 \(unless that pushes overall line to be longer than 100\)\. That is, I want layout like this \(using 20/30 rulers instead of 70/100, for illustrative purposes\):
```
// Top level comments
// can be this wide.
const S = struct {
// Nested comments are
// also this wide, but
// are shifted right.
fn f() void {
switch (value) {
0 => {
// But there is
// a hard limit.
}
}
}
}
```
This feels obvious in retrospect, but notably isn’t be well\-supported by the tools? The[VS Code extension](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap)I use allows configuring dedicated fill column for comments, but doesn’t make it*relative*, so indented comment blocks are always narrower than top\-level ones\. Emacs`M\-q`also doesn’t do relative wrapping out of the box\!
---
Aside on hard\-wrapping: should we bother with wrapping comments at all? Can’t we rely on our editor to implement soft\-wrapping? The problem with soft\-wrapping is that you can’t soft\-wrap text correctly without understanding its meaning\. Consider a markdown list:
```
A list:
* item one,
* item two.
```
If the first item is long enough to necessitate wrapping, the wrapped line should also be indented, which requires parsing the text as markdown first:
```
A list:
* item one which is long enough
necessitate wrapping,
* item two.
```
Similar Articles
@the_smart_ape: https://x.com/the_smart_ape/status/2053034897514660074
A commentary on the ongoing debate between Markdown and HTML usage in development, suggesting that the polarization is counterproductive and referencing Claude Code's influence.
Nontrailing separators do not spark joy
The article argues that disallowing trailing separators (like commas) in programming languages and data formats makes code editing more error-prone and less consistent, and advocates for language designs that permit trailing separators for better developer experience.
Using Claude Code: The unreasonable effectiveness of HTML
A blog post by a Claude Code team member argues for using HTML instead of Markdown as the preferred output format for AI agents like Claude Code, citing benefits such as richer information density, visual clarity, ease of sharing, and interactive capabilities.
Does anyone else hate the no-IDE trend
A developer criticizes the trend of AI coding tools removing code editors in favor of standalone chat interfaces, arguing it wastes tokens and ignores the needs of technical users who prefer managing code output within an IDE.
Coding Models Are Doing Too Much
A blog post investigating the "Over-Editing" problem where coding LLMs rewrite more code than necessary when fixing simple bugs, proposing metrics and training approaches to encourage minimal, faithful edits.