Skip to main content

Trailing Comments

A comment that follows a token on the same source line describes that token, and it stays on that token's line in the output. Only a comment on its own source line (or the first line of a statement) is treated as a leading comment of what follows.

Trailing line comments stay on their item's line​

select
  dateadd(day, 90, current_date) as d,
  a, -- first col
  b, -- second col
  case when x = 1 then 'a' /* why */ else 'b' end as c
from t
select
    dateadd(day, 90, current_date) as d,
    a, -- first col
    b, -- second col
    case when x = 1 then 'a' /* why */ else 'b' end as c
from t

Trailing comment on the last item stays put across the clause boundary​

The comment after the final select item must not migrate below the item, where it would read as a header for the FROM clause.

select
  argmin(price_usd, last_updated_utc) as open_usd, -- first in day
  argmax(price_usd, last_updated_utc) as close_usd -- last in day
from base
select
    argmin(price_usd, last_updated_utc) as open_usd, -- first in day
    argmax(price_usd, last_updated_utc) as close_usd -- last in day
from base

Own-line comments still lead the next item​

select
  first_long_column_name,
  second_long_column_name,
  -- section two
  third_long_column_name,
  fourth_long_column_name
from some_table_name
select
    first_long_column_name,
    second_long_column_name,
    -- section two
    third_long_column_name,
    fourth_long_column_name
from some_table_name

Trailing block comment stays inline​

select a /* the key */, b from t
select a /* the key */, b from t

A trailing comment forces its container to break, and the break keeps the indent​

A line comment claims the rest of its line, so nothing may follow it there. That has to be known when the layout decides whether the container fits, not only when the text is emitted: a container that believes it fits renders flat and establishes no indent, and the break the comment then forces lands the continuation at column 0.

The comment attaches to the token it follows — for a, -- one that is the comma, a separator rather than an item — so the separator has to be consulted too.

select a, -- one
  b,
  c
from t
select
    a, -- one
    b,
    c
from t

Without the comment the same list stays on one line​

The break above is caused by the comment, not by the list. Nothing else changed.

select a,
  b,
  c
from t
select a, b, c from t

A same-line comment before a separator still trails its own token​

A comment on the previous token's line belongs to that token.

select a /* the key */, b from t
select a /* the key */, b from t

A trailing comment has no width​

Layout is decided on the code alone; a trailing comment rides on whatever the last line turns out to be. So a comment never reshapes the code it annotates, and the code below stays on one line even though the comment takes it past the budget.

The alternative — letting the comment exert width pressure — makes a expression's shape a function of the length of the prose attached to it, so editing a comment reflows code and the diff is noise. It does not even remove the overflow: breaking the code only moves the comment onto a shorter last line, it cannot make the comment shorter.

select
  argmin(price_usd, ts) as open_usd, -- the first observed price of the day, from the earliest timestamp
  bbb
from base
select
    argmin(price_usd, ts) as open_usd, -- the first observed price of the day, from the earliest timestamp
    bbb
from base

Code over the budget still breaks, and the comment rides the last line​

The rule is about the comment not adding pressure, not about suppressing pressure the code already has. Here the expression exceeds the budget on its own, so it breaks, and the comment stays with the line the item ends on.

select
  coalesce(alpha_column_name, bravo_column_name, charlie_column_name, delta_column_name) as v, -- short note
  bbb
from base
select
    coalesce(
        alpha_column_name,
        bravo_column_name,
        charlie_column_name,
        delta_column_name
    ) as v, -- short note
    bbb
from base

A comment run in front of a separator does not strand the separator​

A commented-out list item leaves the following comma with a comment run in its leading trivia. The comma still belongs to the item before it, so it glues there and the run renders above the item it precedes — a lone , on a line of its own is not output anyone can defend.

select
  full_liste.sortering as sortering_fylke
  --,case when count(distinct mottaker.fk_person1) < 10 then
  --         round(count(distinct mottaker.fk_person1)+5, -1)
  --  else count(distinct mottaker.fk_person1)
  --end antall
  ,
  count(distinct barn.fkb_person1) as antall
from t
select
    full_liste.sortering as sortering_fylke,
    --,case when count(distinct mottaker.fk_person1) < 10 then
    --         round(count(distinct mottaker.fk_person1)+5, -1)
    --  else count(distinct mottaker.fk_person1)
    --end antall
    count(distinct barn.fkb_person1) as antall
from t

The forwarded run is then an ordinary leading comment​

Which means a comment written on the PREVIOUS item's line still trails that line: forwarding hands the run to the next item with the separator as its preceding token, and same-line attachment takes it from there.

select
  a -- note about a
  , b
from t
select
    a, -- note about a
    b
from t

Leading-comma style keeps the run above the separator​

With the comma at the head of its line the run already reads correctly, and forwarding would create exactly the stranded separator it exists to remove.

select
  a
  -- note
  , b
from t
select
    a
    -- note
    , b
from t