Re: How do I prototype a function with a varying number of arguments?

Your commenting style hit me in the face like a 1960s COBOL manual. Generally, you are "over commenting". You need to get to the point. Be precise and succinct. Maintenance programmers are often under time pressure. Don't force them to wade through unnecessary comments, "conversational" comments, or witty jokes to get to the meat. A couple of examples of poor commenting from your code:

# 
   # setup requirements, eat your greens
   #
[download]

This comment is unnecessary and jokes like these get old very quickly.

   # 
   # Return the value.
   #
   return $value;
[download]

Don't belabour the obvious!

Perl Best Practices has an excellent chapter on Documentation, which I recommend you read. Some commenting tips (taken from On Coding Standards and Code Reviews):

Separate user versus maintainer documentation.
Prefer to make the code obvious.
Don't belabour the obvious.

A couple of other things I noticed:

In addition to "use strict", don't forget about "use warnings".
Don't put "use" statements inside subs (see Code style advice: where to put "use" statements?).
Unpack subroutine arguments at the top of the sub. Update: This is discussed in Chapter 9, "Subroutines" of Perl Best Practices in the third item "Always unpack @_ first". Luckily, Chapter 9 happens to be the free sample chapter from this book.
Declare variables at point of first use. Minimize variable scope. For example, remove the big ugly block of variable declarations near the top of your sub and replace "foreach $time ..." with "foreach my $time...".
To make code easier to read, suggest white space around operators (e.g. $value="0".$value -> $value = "0" . $value).
Don't use prototypes.

Comment on Re: How do I prototype a function with a varying number of arguments? Select or Download Code

Replies are listed 'Best First'.
Re^2: How do I prototype a function with a varying number of arguments? by JavaFan (Canon) on Jul 30, 2011 at 10:08 UTC
The "unpack subroutine arguments at the top of the sub" and "declare variables at point of first use" don't always see eye to eye to each other. In fact, the former tends to create a "big ugly block of variable declarations near the top of your sub", something the latter doesn't want to see.	[reply]
Re^3: How do I prototype a function with a varying number of arguments? by eyepopslikeamosquito (Archbishop) on Jul 30, 2011 at 13:45 UTC
In general, the consensus is that Perl 5's simple subroutine syntax is just a little too simple. Well, okay, it's a lot too simple. While it's extremely orthogonal to always pass all arguments as a single variadic array, that mechanism does not always map well onto the problem space. -- Larry Wall in Apocalypse 6 (2003) Yes, I see your point, so let me clarify. Minimizing variable scope is a sound general programming practice that I strive to employ in all languages I currently use (C++, Perl, Python, Ruby, Java). That is my strategic goal. This "unpack subroutine arguments at the top of the sub" business is just a pragmatic tactic used to work around Perl 5's primitive subroutine syntax. That is, in most languages, the scope of function arguments is the whole function and that is made plain by the language syntax. Explicitly unpacking Perl's appallingly non-descriptive `$_[0]`, `$_[1]`, ... subroutine argument names at the top of the subroutine to more meaningful lexically scoped names is usually the clearest way to express that these are indeed the function's arguments and that their scope is accordingly the whole function. In the common case of read-only subroutine arguments, it is also safer in that it avoids accidentally changing the passed arguments. The reasons behind this rule are described in detail in Perl Best Practices, along with exceptions to this rule (e.g. short and simple subs, when efficiency is critical, ...).	[reply] [d/l] [select]
Re^2: How do I prototype a function with a varying number of arguments? by pemungkah (Priest) on Jul 31, 2011 at 19:10 UTC
And see On comments for a long discussion between BrowserUK and I about the meaning and value of comments. BrowserUK is strictly a minimalist (or perhaps a zeroist), and feels comments only get in the way, and I'm a semi-maximalist, who feels that comments should be there to clarify intent, point out pitfalls, and explain complex code to the reader. That said, I too agree that comments which simply mirror the code are not needed. In the example noted, the comment is not needed; if there were some specific limitation on what the return value should be or a special case that might occur, a comment would be a good idea. That's a marginal case and might or might not be better put in the POD for the subroutine (which should also be there); it would depend on the context. In an internal-use-only subroutine that was not part of a documented external interface, I'd use a comment; in a published, intended-for-use-without-reading-the-code situation, I'd put it in the POD.	[reply]
Re^3: How do I prototype a function with a varying number of arguments? by JavaFan (Canon) on Jul 31, 2011 at 21:15 UTC
BrowserUK is strictly a minimalist (or perhaps a zeroist), and feels comments only get in the way, and I'm a semi-maximalist, who feels that comments should be there to clarify intent, point out pitfalls, and explain complex code to the reader. I tend to be both. I feel comments should be there to clarify intent, etc. I also prefer to have as few comments as possible. Impossible you say? I disagree. If your code is simple enough, there just isn't much reason to add a comment. If I feel the need to write a comment to explain my code - I also consider rewriting the code instead so the comment may no longer be needed.	[reply]
Re^4: How do I prototype a function with a varying number of arguments? by pemungkah (Priest) on Aug 08, 2011 at 17:47 UTC
Completely agree on both these points. Sometimes you just have to explain what the heck is going on because there are reasons you had to do it that way (the kernel bug I reference in my post is an example). If it is possible to clarify to eliminate the need for the comment without sacrificing performance or correctness then I'm all for the code that doesn't need it.	[reply]
Re^2: How do I prototype a function with a varying number of arguments? by lyapunov (Novice) on Aug 01, 2011 at 21:46 UTC
Thank you all for the constructive criticism and food for thought. I have never enjoyed having a mentor. It has largely been on my own (I guess that shows). I have had the misfortune of dealing with other people's code where nothing was commented and the code was, at least for me, not intuitive in any way. As a matter of fact, I can't think of a single program that I have had to tweak that had comments. As a result, I have been over-compensating, I will take a page from your book and Strunk and White's, and keep it brief. I will rework this week and repost it to you, if you don't mind, to see if it is up to scratch. Again, thanks. I am happy to have this place, and people like you that will help folks along the way. Cheers!	[reply]