Using Plain-Text Tables in Source Comments and Code Reviews

Source comments and code reviews are not the place for large reports, but small tables can be very useful. A table can summarize flags, migration cases, browser support, error states, or compatibility rules without forcing the reader to scan a long paragraph.

The challenge is that source files and review tools have constraints. Lines should stay modest. Formatting should be stable in monospaced fonts. The table should not make the code harder to maintain.

Use tables for compact reference data

Good source-comment tables usually have two to four columns:

+---------+----------+----------------+
| State   | Retry    | User message   |
+---------+----------+----------------+
| timeout | yes      | Try again      |
+---------+----------+----------------+
| denied  | no       | Check access   |
+---------+----------+----------------+
| invalid | no       | Fix input      |
+---------+----------+----------------+

This works because each row has the same shape. The table gives maintainers a quick map of behavior.

Avoid using a table for a full design essay. If a cell needs multiple sentences, write paragraphs or link to a design document.

Keep max line width modest

Many repositories still prefer lines near 80 or 100 columns. Even when the codebase allows longer lines, comments are easier to read when they stay narrow.

Use short headers:

Prefer	Avoid
State	Current processing state
Retry	Should the operation be retried
Message	User-facing fallback message

If a header has to be long, the table probably wants a paragraph instead.

Match the comment style

Different languages have different comment conventions:

// +--------+----------+
// | Format | Use      |
// +--------+----------+
// | grid   | comments |
// +--------+----------+

# +--------+----------+
# | Format | Use      |
# +--------+----------+
# | grid   | comments |
# +--------+----------+

If you need to paste the table into a source file, add the comment prefix after conversion or use your editor’s block comment command. Do not include the comment marker inside the original Markdown table; it makes the source harder to reuse.

Prefer ASCII over Unicode for source files

Unicode box drawing can look excellent in terminals, but ASCII is safer in source comments:

Output	Source comment fit
Grid ASCII	Most compatible
Unicode box	Good only if the repo already uses Unicode
Simple text	Best when space is tight

ASCII avoids encoding surprises and works in older diff tools. Unicode is fine when your repository already accepts Unicode characters in comments and documentation.

Review comments need even shorter tables

Code review comments are read in narrow panels. A three-column table may wrap. For review tools, consider Simple text:

Case       Expected   Notes
---------  ---------  ----------------
empty      warn       keep output
escaped    literal    show pipe
invalid    preserve   keep prose

This format is compact and easy to edit if the review discussion changes.

Maintenance rule

Only put a table in source when it helps future maintainers make a decision faster. If the table repeats code that is already obvious, skip it. If it explains a mapping that is otherwise scattered across conditions, it can be valuable.

A useful plain-text table in source is small, stable, and boring in the best way: it keeps the reader oriented without becoming another thing to debug.