Skip to content
Alignment№ 33strip-trailing-commasstrip-stranded-paddingnormalize-comment-spacingline-overflow

align-comments ​

align-comments pads the gap before each trailing comment in a so every # sits at one shared , and the notes then read straight down beside the code they describe. Without it a trailing comment starts wherever its line of code stops, so a block of annotated lines opens its notes at a different offset on every row even after the assignments beside them share a column, and the eye tracks two ragged edges instead of one.

The rule reads the trailing comments in source order and extends a run while each next comment sits on the line directly below the last. A line with no trailing comment, a , and an each end the run, and a run whose rows sit at differing indents gets no column at all, since a shared column would sit where neither row's code ends. The shared column sits two spaces past the widest row in the run, the gap normalize-comment-spacing sets, which keeps every aligned row at or above the PEP 8 minimum.

A row that reaches no shared column takes the two-space minimum instead, which is how a hand-set gap lining up with nothing . That covers a lone trailing comment, since a run of one has no column to share, and it covers a row that leaves its run. Two limits split a row out of a run, the rule's max-shift limit and the code-line-length , where a row whose aligned line would cross the budget stays where it sits rather than creating an overflow for line-overflow to report.

The RETRY_DELAYS list holds one entry per line, and 1, 30, and 3600 differ in width, so each trailing comment starts at a different . The three comments move to one column two spaces past 3600, because the entries sit at one indent on consecutive lines and so form one , leaving the notes reading as a second column beside the values.

RETRY_DELAYS = [
    1,    # immediate
    30,   # after the first failure
    3600  # hourly from here on
]
python

The column resolves to two spaces past the widest row whether that moves a comment right or left, so a run whose notes already line up at a wider gutter tightens onto that same column. The alignment the author drew survives, with the slack past it removed the way strip-stranded-padding removes padding that lines up with nothing.

The three DECODING_TABLE entries carry a wide hand-set gutter that already lines their comments up in one . The gutter closes as a block to two spaces past the widest row, because the shared column resolves at that offset whatever gap the input carries, so the alignment the author wrote survives at the tighter column.

DECODING_TABLE = {
    0x0080 : 0x00C7,  # LATIN CAPITAL LETTER C WITH CEDILLA
    0x0081 : 0x00FC,  # LATIN SMALL LETTER U WITH DIAERESIS
    0x0082 : 0x00E9   # LATIN SMALL LETTER E WITH ACUTE
}
python

warm_the_cache_now(), reconcile_open_charges(), and flush_writes() each carry a trailing comment, and the comment on flush_writes() is long. The first two rows align on one and flush_writes() keeps its two-space minimum, because padding it out to the shared column would push its line past code-line-length, and the rule never creates an overflowing line.

warm_the_cache_now()      # cheap
reconcile_open_charges()  # slow
flush_writes()  # padding this one out to the shared column would cross the budget
python

A # prose: skip on a row is itself that row's trailing comment, so the row stays in the run while the column math leaves it out, and the rows above and below it align together.

Configuration ​

KeyTypeDefaultMeaning
enabledbooltrueTurns the rule on or off.
max-shiftpositive int | 0 | false16How far apart the widest and narrowest rows of a may be for the run to still align on one . A positive N caps that gap, 0 forbids any padding so every row sits flush, and false removes the cap so a run of any width aligns on one column. A row marked # prose: skip stays out of its .

Under max-shift = 0, every trailing comment sits at the two-space minimum.

The Canonical Case ​

attempts, threshold, and window each carry a trailing comment, and each comment starts wherever its own code ends. Every # in the moves to the two spaces past the widest line, threshold = 200, so the read down one edge the way the assignments beside them already do.

attempts  = 1    # retries before the backoff widens
threshold = 200  # rows per flush
window    = 30   # seconds
python

More Examples ​

seed(), flush_all(), and warm_now() carry comments padded by hand to one , and the case runs with max-shift = 0. Every hand-set gap closes to the two spaces PEP 8 prescribes, because 0 forbids padding altogether, so no comment moves to meet another and each row stands alone.

prose.toml
toml
[rules.align-comments]
max-shift = 0

seed() and reconcile_every_pending_shipment_record() each carry a trailing comment, and the case runs with max-shift = false. The # after seed() moves all the way out to the reconcile_every_pending_shipment_record() sets, rather than falling back to the two-space minimum, because false removes the limit on how much padding one row may take, so a the default limit would split aligns on one column.

prose.toml
toml
[rules.align-comments]
max-shift = false

foo() carries a bare # with no text after it, and barbaz() below it carries # note. The bare # moves to the same as # note, because the rule measures only the code before each # and never reads what follows the hash, so a bare # joins the like any other trailing comment.

Two annotated calls sit above a and two more sit below it. The blank line ends the , so warm_the_cache() and seed() share one comment and flush() and compact_the_index() share another. Each column is measured from the rows it spans alone, so the wider second pair pushes only its own # further right.

flush() carries the only trailing comment in the module, written with a wide gap before its #. The gap closes to two spaces, because one annotated line is not a and so has no shared , the same spacing a row takes when it leaves a run.

compact_the_index() carries a # prose: skip[align-comments] directive between the annotated seed() and flush(). seed() and flush() align on one measured from their own widths alone, because the skipped row neither moves nor ends the , so its comment stays where it was written and the rows on either side of it bridge across.

seed() and reconcile_every_pending_shipment_record() each carry a trailing comment, and the one after seed() is padded by hand to line up with the other. The hand-set gap after seed() closes to two spaces, because the two rows differ in width by more than max-shift allows, so neither reaches the other's and each stands alone at the two-space minimum.

counter = 1 carries a #: Sphinx attribute doc and n = 20 carries a # type: ignore pragma, two openers normalize-comment-spacing leaves as written. Both comments still align on one shared , because that exemption covers what a comment opens with rather than where it sits.

An sits between seed() and flush() in a stretch of four annotated calls. The own-line comment ends the above it and never joins a , so warm_the_cache() and seed() align on one column, flush() and compact_the_index() align on another, and the comment stays flush at the indent it was written on.

seed() and flush() form a whose two # already sit on the the widest row sets. The rule emits no edit, because every row's target column matches the one it already occupies, and the rule never reports a fix that would change no bytes.

flush() sits indented inside the if ready: branch and compact_the_index() sits at , each with a trailing comment. Neither comment moves, because the two rows open at different indents and so never form one , leaving both the two-space gap they already carry.

  1. retries, timeout_seconds, and window are annotated assignments with trailing comments, and three alignment rules pad the same rows, each checking its own padding against the 72-column . Every rule measures the row's form rather than the intermediate text the rule before it left, which is what lets the :, the =, and the # all reach their with the widest row, retries, still inside the budget.

Formatting

normalize-comment-spacing

Puts one space after a comment's hash run and at least two spaces between code and a trailing comment.

Alignment

align-equals

Pads the space before = so consecutive assignments, annotated parameter defaults, and an exploded call's keyword arguments share one column.

Alignment

align-colons

Pads the space before : so consecutive dict entries, annotated assignments, signature annotations, and docstring entries share one column, with a docstring entry's parenthesized type in a column of its own.

Lint

line-overflow

Reports a line still over its line budget once no layout rule can shorten it.

Alignment

strip-stranded-padding

Removes padding that lines up with nothing, before the : of a one-member group and just inside a bracket, and settles the gap after a : to one space.

0.11.0Versione83e7e6Commit43Rules1830Fixtures2026-11-19Updated