On 6/15/19 1:14 PM, Bruno Haible wrote:
I found that they got in the way of my understanding the code
Do you mean, we should highlight the comment about the program itself?
Partly that - the first comment of a script should be very brief
(typically one line) and say what the script does; it shouldn't jump
into gory implementation details. Your suggestion to use a followup
comment with fancy highlighting characters is less useful to my eyes;
I'm used to the more-standard convention of a short comment first.
But mostly because it's a big blob of text that just gets in the way of
likely readers. A brief reference to perlrun will be better both for
readers who already know this stuff (and don't need the details, just a
reminder) and for readers who don't (for which the comment itself is a
big and barely-understandable blob and will require reading perlrun and
other stuff anyway). At least, that's how the comment strikes this
particular reader.
But I won't fight about it.
