Re: On /*----- comments

On 03/07/2023 11:48, Daniel Gustafsson wrote:
>> On 30 Jun 2023, at 17:22, Tom Lane <tgl@sss.pgh.pa.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)