Discussion [postgres]: How to format `COMMENT` statements spanning multiple lines

[joelmukuthu]

This:

COMMENT ON COLUMN loooooooooooooooooooooooooooooooooooooooooong_column_name IS E'foo'; 

Gets formatted as:

COMMENT ON COLUMN loooooooooooooooooooooooooooooooooooooooooong_column_name IS 
  E'foo'; 

While this would be slightly easier to scan:

COMMENT ON COLUMN loooooooooooooooooooooooooooooooooooooooooong_column_name
  IS E'foo'; 

Or perhaps:

COMMENT 
  ON COLUMN loooooooooooooooooooooooooooooooooooooooooong_column_name 
  IS E'foo'; 

What do you think?

[nene]

Yep, your proposal looks better than the current implementation 👍

I'd go with the first version, so it would be just two lines instead of three.

One thing that might need additional thought is how one would format a comment on a function with long parameter list. Currently it looks like so:

COMMENT ON FUNCTION my_absolutely_fantastic_function(
  IN whoopsie CHARACTER VARYING,
  OUT doopsie TEXT
) IS
  'This is a really nice comment here.'

In the new style I guess it could look like this:

COMMENT ON FUNCTION my_absolutely_fantastic_function(
  IN whoopsie CHARACTER VARYING,
  OUT doopsie TEXT
)
  IS 'This is a really nice comment here.'

But that location of the closing ) feels a bit off. So maybe better to break it apart like so:

COMMENT ON FUNCTION
  my_absolutely_fantastic_function(
    IN whoopsie CHARACTER VARYING,
    OUT doopsie TEXT
  )
  IS 'This is a really nice comment here.'

That way we can also handle really long column names similarly:

COMMENT ON COLUMN
  loooooooooooooooooooooooooooooooooooooooooong_column_name 
  IS E'foo'; 

Anyway, feel free to have a go at implementing this. It should be relatively easy to find the code that handles this COMMENT ON syntax formatting. Search for comment_stmt.

[nene]

Or, on second thought, perhaps that original idea of yours would actually be better in these scenarious. Formatting it like:

COMMENT ON
  FUNCTION my_absolutely_fantastic_function(
    IN whoopsie CHARACTER VARYING,
    OUT doopsie TEXT
  )
  IS 'This is a really nice comment here.'

That should also make the implementation easier, as the [FUNCTION name(params)] part is parsed as a separate node.

Anyway, I don't really mind either way. Like, perhaps ideally we would wrap the code from 1 to 2 to 3 lines as it gets longer:

COMMENT ON COLUMN foo IS 'my comment'; 

COMMENT ON COLUMN foo
  IS 'my very long comment'; 

COMMENT ON
  COLUMN very_long_column_name
  IS 'my very long comment'; 

But really I think it's actually fine to jump immediately from 1st variant to 3rd.

[joelmukuthu]

Nice! I very much like your final suggestion:

COMMENT ON COLUMN foo IS 'my comment'; 

COMMENT ON COLUMN foo
  IS 'my very long comment'; 

COMMENT ON
  COLUMN very_long_column_name
  IS 'my very long comment'; 

I like the determinism in only supporting the 1st and 3rd variants so formatting changes less often. But I'll let it simmer a bit more before I pick it up. Thanks for the suggestion!