Beefy Boxes and Bandwidth Generously Provided by pair Networks
Syntactic Confectionery Delight
 
PerlMonks  

Re: flower box comments

by Ninthwave (Chaplain)
on Nov 17, 2003 at 14:24 UTC ( #307660=note: print w/replies, xml ) Need Help??


in reply to flower box comments

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

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://307660]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others having an uproarious good time at the Monastery: (9)
As of 2019-09-16 16:09 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    The room is dark, and your next move is ...












    Results (196 votes). Check out past polls.

    Notices?