Read the thread. There are a lot of replies that point out issues with that coding style and the specific example. There are no replies that find it the epitome of good style.

The post you have chosen to reply to is over 17 years old. The user who asked the question hasn't logged in for over 6 years. Necrobumping such threads is unlikely to be constructive.

> Necrobumping such threads is unlikely to be constructive.

I think, while the OP won't reply, the following discussion is still relevant and interesting.

KABA should read the thread tho, if he wants to add new aspects.

Cheers Rolf
_{(addicted to the Perl Programming Language :)
Wikisyntax for the Monastery}

There may be something more going on than just a new user finding an old post and replying to it.

All of the original discussion took place over ~12hr period back in 2003. Now today (2021), out of the blue, AM replies to the OP with "In my opinion your code looks just fine." followed three minutes later with KABA also replying to the OP with "I do not see anything wrong with that.".

— Ken

Both comments were by KABA, but the first one was made while not logged in. I have considered it for reap for that reason.

Yes, it's quite the mystery! Like a Sherlock Holmes story. :) I assumed AM found the 2003 post via google and (not noticing the 2003 date) simply banged out a reflex AM reply ... then decided to create a proper PM account and used that to reply three minutes later (still not taking the time to notice how old the post was). jdporter could probably tell us if AM and KABA are one and the same ... or (better), if KABA is still listening, he/she could tell us the back story. I won't be able to sleep tonight not knowing. :)

Hello KABA. Welcome to the Monastery!

The "Comments and Documentation" section at On Coding Standards and Code Reviews seems relevant to your comment, in particular:

• Separate user versus maintainer documentation.
• Include a comment block on every non-trivial method describing its purpose.

These are general guidelines, applicable to any language, not just Perl. Some prefer to comment Perl functions with POD. I find intermingling code with POD doesn't suit my brain, I prefer to put all the POD at the end of the file, and reserve it for public functions only (i.e. the external interface to the component) - I don't use POD to document internal functions.

When I describe a function parameter, I like to state explicitly whether it is an input parameter, an output parameter, or an "inout" parameter ("inout" parameters should be used sparingly).

Put another way, the POD at the end of the file is for the user of the module, the comment blocks at the top of each function are for the maintainer of the module (i.e. separate user versus maintainer documentation). The tricky bit is balancing this with DRY.