Commenting code sacrifices the educational purpose of code for maintainability and laziness.

I'd have to disagree. Commenting code makes it easier to understand, and in doing so, makes it easier to learn from.

First of all, if someone new to Perl who is looking for some code to learn from comes across your code and sees no comments, do you think they'll even bother trying to figure out what it does? If for some reason they do, they might end up making wrong guesses and coming to false conclusions. Including comments will make reading your code less intimidating and give people a basic understanding of your code which they can build upon.

The other side of it is that maintainability is important in publically released code as well. If you want your code to be truly useful to others and want them to reuse it, it needs to be well documented. This is especially important for larger projects.

Taking out the comments from your code will lead to code that is harder to maintain and is less useful to others. Even if comments did have some magical effect making all code with them uneducational, why not let people decide for themselves whether or not they want to take the comments out?

In reply to Re: Commenting One's Code In A GNU/GPL/OpenSource World by cjf
in thread Commenting One's Code In A GNU/GPL/OpenSource World by Revelation

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.