Beefy Boxes and Bandwidth Generously Provided by pair Networks
The stupid question is the question not asked
 
PerlMonks  

comment on

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

I comment like the above. I borrowed this style from my learning back in the 80's and it was how most languages I learned suggested you comment. I hated comments, until I found myself programming in work. And had to revisit my own code. I specifically want to comment on functions and subroutines so I know what arguments and values are returned. This is easy for me as I update a function or subroutine I update the comment and know what the changes are and can quickly check the calls to the subroutine or function.

That said when the script goes live and I am no longer testing it, I trim down the comments and place them in more approiate places for the documentation. POD I am just beginning to explore fully and can not list all its advantages as I was introduced to pod as a means of creating user help files pod2usage. Though from coming here I am starting to see its full nature.

I think in general any commenting that is detailed is great. Converting it to other version is not hard. It would be easy to parse these scripts and change the commenting style. Remember commenting has set formats that perl needs to recognise to not execute comments. You can program a perl script to change your comments when the commenting style changes. So any commenting style can be updated if the need if you find the need to change style later.

So in the style of commenting I believe pod looks like the most flexible way to make your comments useful on many levels. On the decision to mark each function in the code, I appreciate that decision and highly second it.

Update I found this link but specifically an interesting comment on 2 pod || !2 pod:
Canta Forda Computer Laboratory

"No matter where you go, there you are." BB

In reply to Re: flower box comments by Ninthwave
in thread flower box comments by mandog

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, 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?
    Username:
    Password:

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

    How do I use this? | Other CB clients
    Other Users?
    Others about the Monastery: (4)
    As of 2019-10-18 04:30 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      Notices?