Thread: Standardizing the file header?

Hi,

Every time I create a new file that I want to write a file header comment for
I get confused about the order in which we write them.

The main "patterns" seem to be

/*-------------------------------------------------------------------------
 *
 * $filename
 *        $oneline_description
 *
 * $longform_description
 * $over_multiple_lines
 *
 * $copyright
 *
 * IDENTIFICATION
 *        $file_path
 *
 *-------------------------------------------------------------------------
 */

/*-------------------------------------------------------------------------
 *
 * $filename
 *    $online_description
 *
 * $copyright
 *
 *
 * IDENTIFICATION
 *    $file_path
 *
 * NOTES
 *    $longform_description
 *    $over_multiple_lines
 *
 *-------------------------------------------------------------------------
 */

Although there quite a few other patterns.


There's also a fair bit variation about how far the indented sections are
indented, even if otherwise using the same pattern. Just looking at the path
in the line after IDENTIFICATION:

$ git grep -h -A1 'IDENTIFICATION'|grep -v IDENTIFICATION|grep '*'|sed -E -e 's/^( ?\*[ \t]+)[a-z].*$/>\1</' -e
's/\t/t/g'-e 's/ /w/g'|sort|uniq -c
 
      1 >*t<
      1 w*
     10 >w*t<
     92 >w*tt<
     27 >w*ttt<
      3 >w*tttw<
     52 >w*ttww<
    865 >w*tww<
     10 >w*twww<
      2 >w*ww<
     12 >w*wwww<
      2 >w*wwwwww<
      4 >w*wwwwwww<


There are also a few files that don't have the filename on the third lines and
that don't use "IDENTIFICATION".


It probably doesn't make sense to change all the existing files to follow one
pattern (although perhaps some of the "more odd" ones might be worth
adjusting).

But it seems like it'd be good to define one pattern as canonical so one
doesn't have to guess what pattern one should follow when creating a new file.

Thoughts?

Greetings,

Andres Freund

[ file headers follow different patterns ]

It probably doesn't make sense to change all the existing files to follow one
pattern (although perhaps some of the "more odd" ones might be worth
adjusting).

But it seems like it'd be good to define one pattern as canonical so one
doesn't have to guess what pattern one should follow when creating a new file.

Thoughts?

+1. Maybe we could add one or two templates for different sort of files to src/tools.

cheers

andrew

--
Andrew Dunstan
EDB: https://www.enterprisedb.com