Re: On /*----- comments

On 03/07/2023 11:48, Daniel Gustafsson wrote:
>> On 30 Jun 2023, at 17:22, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>
>> Seems reasonable; the trailing dashes eat a line without adding much.
>
> +1

Pushed a patch to remove the end-guard from the example in the pgindent
README. And fixed the bogus end-guard in walsender.c.

>> Should we also provide specific guidance about how many leading dashes
>> to use for this? I vaguely recall that pgindent might only need one,
>> but I think using somewhere around 5 to 10 looks better.
>
> There are ~50 different lenghts used when looking at block comments from line 2
> (to avoid the file header comment) and onwards in files, the ones with 10 or
> more occurrences are:
>
> 145 /*----------
> 78 /*------
> 76 /*-------------------------------------------------------------------------
> 37 /*----------------------------------------------------------
> 29 /*------------------------
> 23 /*----------------------------------------------------------------
> 22 /*--------------------
> 21 /*----
> 15 /*---------------------------------------------------------------------
> 14 /*--
> 13 /*-------------------------------------------------------
> 13 /*---
> 12 /*----------------------
>
> 10 leading dashes is the clear winner so recommending that for new/edited
> comments seem like a good way to reduce churn.

The example in the pgindent README also uses 10 dashes.

I'm not sure there is a universal best length. It depends on the comment
what looks best. The very long ones in particular would not look good on
comments in a deeply indented block. So I think the status quo is fine.

> Looking at line 1 comments for fun shows pretty strong consistency:
>
> 1611 /*-------------------------------------------------------------------------
> 22 /*--------------------------------------------------------------------------
> 18 /*------------------------------------------------------------------------
> 13 /*--------------------------------------------------------------------
> 7 /*---------------------------------------------------------------------------
> 4 /*-----------------------------------------------------------------------
> 4 /*----------------------------------------------------------------------
> 1 /*--------------------------
>
> plpy_util.h being the only one that sticks out.

I don't see any reason for the variance in these. Seems accidental..

--
Heikki Linnakangas
Neon (https://neon.tech)