Beefy Boxes and Bandwidth Generously Provided by pair Networks
Just another Perl shrine

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
Good commenting can:

What about s/Good commenting can:/Good coding can:/ ? And that's the main point.

  • make you describe what is intended.

    That can, and should be done with code proper.

  • make you to consider edge conditions and check that cases that need to be covered are covered. You should do that anyway, of course, but if you write it down it's more concrete.

    What is better than code which considers edge conditions, naming the conditions by proper set branches and variables? The requirements are (or should be) in the specs. Code is no place for that.

  • require you to express and examine assumptions

    that is what we do all time along coding perl. Anything which can't be done that way needs to be cleared beforehand and laid down in the specs.

  • justify and document the choice of algorithm or method.

    The choice of algorithm is done per knowledge. Now, you wouldn't document your knowledge in any (every?) piece of code you write, would you? Algorithms can be named, if they have a name. If they work out to the specs, that's fine. If they don't, they are changed, and describing the "why and whence and how" sayings doesn't add anything to the comprehensiveness of the code. The code should be written to be comprehensive in the first place.

  • leave notes on things which were not obvious when you worked out what needed to be done or how to do it

    This is the only reasonable item in the list - quoting Kernighan: "Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it."

    Teaching perl, the first code samples of your pupils are like that:
    open my $h, '>', $file # try to open a file or die "Can't open '$file' for writing: $!\n"; # if that fails, te +rminate with a message while(<$fh>) { # reading a line via <$fh> assigns per default +to $_ s/foo/bar/; # s/// operates per default on $_ }
    That's okay, since they want to remember what they have learned. Maintaining code and refactoring is a totally different issue. If you do that, you have to toss around code, and having comments piggyback is - piggyback, and a burden. If every EXPR is written properly; if every STATEMENT is clearly written; if every BLOCK defining a SCOPE containing STATEMENTS which are comprehensible on their own, or as part of the enclosing PACKAGE, or APPLICATION to which they apply, everything is fine.

I choose to code in perl (also ;-) because that way I have a wealth of expressions at hand which makes - or could make, if I work up to my level of experience - the code self-explanatory. And that's the goal. Anything below that can only be badly mended with comments. They are workarounds. Your program is a technical paper, which should be readable on its own by technicians of the same craft, but not necessarily for pupils (unless you are a teacher) or laymen. Those technicians which can't need teaching (by themselves, or training by somebody else), and that fact cannot be mended with comments either.

In reply to Re^2: Why no comments? by shmem
in thread Why no comments? by targetsmart

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, 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, 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.
  • Log In?

    What's my password?
    Create A New User
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others pondering the Monastery: (4)
    As of 2020-10-30 03:04 GMT
    Find Nodes?
      Voting Booth?
      My favourite web site is:

      Results (277 votes). Check out past polls.