As someone who has had to support 8,000 line perl scripts with single line comments every 300 or so lines in Italian, I can say that for me, more comments are better than less comments, in general...

I've found myself having to support so many other people's scripts (AWK, Shell, Perl, etc) that my most beloved comment is the "explination" comment block which basically states what the next block of code is supposed to do, why and even the expected output (an extra special point if they put in their thought processes)... I know for some, this is too much commenting, but when you are supporting a script that no-body's done anything with for two years and no-one has any idea of what was behind the programming, these type of comment blocks can save DAYS of rehashing, esp. if there are multiple calls to other scripts and exported veriables...

# 
# This next block was actually put in because
# Joe Manager needed to see the output as a
# webpage and not as a text mail. (Fair enough.)
# The output (amid the html code) should look
# something like:
#
# Logins       User-ID      Real Name
# ------------------------------------
#   8          3rtulla      Arthur Tulla
#

[download]
My opinion is that good scripts are maintainable by people who know less than you about the code, don't want to learn (necessarily) to program in that language and need to update or change that script quickly. Good commenting is how this can easily be acheived.

okay, after re-reading this posting, i see it has a heavy sysadmin bent... my hand is revealed... =)

magnus

In reply to Re: The art of comments: (rave from the grave) by magnus
in thread The art of comments: (rave from the grave) by BrowserUk

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.