|Syntactic Confectionery Delight|
Re: flower box commentsby Ninthwave (Chaplain)
|on Nov 17, 2003 at 14:24 UTC||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.
I found this link but specifically an interesting comment on 2 pod || !2 pod:
"No matter where you go, there you are." BB