Skip to main content

Leading Comments

A comment on its own line annotates the line below it — it stacks ABOVE that line and must not change how the line itself is laid out. Before this was said, a leading comment counted as the construct "coming apart": the commented item exploded across its brackets while its identical uncommented sibling stayed on one line, which is the single most visible "the formatter is broken" tell a review can produce.

A commented item keeps the layout of its uncommented siblings​

select
  id,
  -- Encerrados
  case when data_fim is not null then 1 else 0 end as encerrado,
  case when data_fim is null then 1 else 0 end as aberto
from t
select
    id,
    -- Encerrados
    case when data_fim is not null then 1 else 0 end as encerrado,
    case when data_fim is null then 1 else 0 end as aberto
from t

A commented parenthesized expression stays on one line​

The paren carries the comment (it is the item's first token), and the comment stacks above the whole item — the tiny expression does not open across three lines.

select
  id as order_item_id,
  ---------- properties
  (order_total / 100.0)::float as order_total,
  (tax_paid / 100.0)::float as tax_paid
from source
select
    id as order_item_id,
    ---------- properties
    (order_total / 100.0)::float as order_total,
    (tax_paid / 100.0)::float as tax_paid
from source

A commented CASE arm keeps its when/then whole​

select case
  when i.category in ('Clinic', 'Incident') then 'Non-Behavioral'
  -- Miami-only
  when i.category_tier in ('T4', 'T3') then 'Low'
  when i.category_tier = 'T1' then 'High'
  end as x
from t
select
    case
        when i.category in ('Clinic', 'Incident') then 'Non-Behavioral'
        -- Miami-only
        when i.category_tier in ('T4', 'T3') then 'Low'
        when i.category_tier = 'T1' then 'High'
    end as x
from t

A commented VALUES row stays inline beside its siblings​

select * from (values
  -- 2019
  ('2019-01-01'::date, 'New Year''s Day'),
  ('2019-01-21'::date, 'MLK Day'),
  ('2019-02-18'::date, 'Presidents'' Day')
) as t(d, name)
select *
from (
    values
        -- 2019
        ('2019-01-01'::date, 'New Year''s Day'),
        ('2019-01-21'::date, 'MLK Day'),
        ('2019-02-18'::date, 'Presidents'' Day')
) as t(d, name)

A comment mid-line still forces a break​

The excusal is positional: only a comment above the FIRST token of a line stacks above it. A trailing line comment claims the rest of its line, so content after one starts a new line — and a list that cannot be one line stacks whole.

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

A block comment's body is indented from its opener​

A /* … */ comment is one element across several lines, and its FRAME belongs to its opener: the layout may move where the comment starts — here the comment leads a select item, so its opener lands at the item column — and when it does, body lines sit one indent level in from the opener's landing column and the closing */ returns to the opener's own column. Left at the author's columns the block is sheared off its own opener, and the deeper the layout takes the statement the further the body is stranded to the left of the comment it belongs to.

Only the frame is normalized: internal relative raggedness — a line the author indented deeper than its siblings — travels. The shallowest body line lands at exactly one level, which is also what makes the frame a fixed point across passes.

with issue as (
    select *
    from t
), macro as (
    select
        /*
        A note about the column below.
        It runs to two lines.
        */
        id
    from issue
)
select * from macro
with
    issue as (select * from t),

    macro as (
        select
            /*
                A note about the column below.
                It runs to two lines.
            */
            id
        from issue
    )
select *
from macro
with issue as (
    select *
    from t
), macro as (
    select
        /*
        A note about the column below.
        It runs to two lines.
        */
        id
    from issue
)
select * from macro
with
    issue as (
        select *
        from t
    ),

    macro as (
        select
            /*
                A note about the column below.
                It runs to two lines.
            */
            id
        from issue
    )
select *
from macro

A blank below a file-header comment survives​

The author separated the header FROM the statement — the blank says this comment does not annotate the line below it. Attaches-downward governs which side a comment renders on, not whether the author's grouping between the comment and its neighbour survives; an empty line is meaning under every mode but none.

-- header comment

select 1 as a
-- header comment

select 1 as a