All the Perl that's Practical to Extract and Report

Games-Bingo-0.01

jonasbn on 2003-05-10T18:39:27

So my first module found its way to CPAN.

I have uploaded Games-Bingo-0.01.tgz to CPAN using PAUSE. Well now I just have to sit back and see how the tests go etc. and I can start to look at some of my other projects.

Some issues

Juerd on 2003-05-11T01:51:50

Some issues:

* The modules have no abstract (In NAME, one usually puts "Module::Name - Module that does something)
* Prototypes are used for methods. That's useless, since they're ignored for runtime thingies. Besides that, have a look at Far More Than Everything You've Ever Wanted to Know about Prototypes in Perl.
* POD is =cut and then immediately continued...
* Some POD is broken otherwise (if you use multiple angle brackets, you must also use whitespace!)

And probably more...

Re:Some issues

jonasbn on 2003-05-11T06:54:30

Thanks!

I will correct these issues ASAP.

I know that the prototypes aren't any good during run-time, but I use them when developing. They work quite well when refactoring code, that is why I tend to keep them around.

Again - thanks for you feedback...

Re:Some issues

Dom2 on 2003-05-11T14:41:07

Hmmm, I don't think you understand prototypes then... Have a look at the referenced article.

In short, prototypes are evil. Don't use them unless you have no other choice (see: Error.pm).

-Dom

Re:Some issues

jonasbn on 2003-05-11T16:36:19

Two things jump out of the the article after a quick-read:
  1. From the 'Great Expectations' section: "Nearly any programmer you encounter will, when asked what function prototypes are for, report the standard text-book answer that function prototypes are mainly used to catch usage errors at compile time in functions called with an unexpected type or number of parameters. This is what programmers are expecting of prototypes, and what Perl does not give them. In some ways, it can't."
  2. From the Summary: "This document is really called Prototypes Considered Harmful"

Excuse me for not going into a technical discussion on some of all Tom's very good examples, but I do not want to question Tom's article and you and Juerds feed-back on prototypes, I just want to explain why I use prototypes.


The article is not a part of the official documentation on Perl and since the official documentation on Perl states a functionality of prototypes in Perl, which resembles what you can find in a standard textbook I guess a lot of people fall into the trap of using prototypes even though considered harmful, well I did anyway.


This snippet is also taken from the perlsub manpage (from Perl version 5.6.0) on prototypes:

"The current mechanism's main goal is to let module writers provide better diagnostics for module users."


So I am put in a somewhat awkward position, since my experience with prototypes has only been a success, as written in my response to juerd I find it very usefull when refactoring (especially other people's code). I know that this in some people's opinion break a rule of refactoring but that is yet another discussion.


This snippet is taken from the perlsub manpage (from Perl version 5.6.0) on prototypes:

"Perl supports a very limited kind of compile-time argument checking using function prototyping."


This is exactly the kind of feature I need and use when refactoring.


I guess somebody should write a paper named 'Official Perl Documentation Considered Harmful', I think some guy tried to raise this issue, but he got scared off.


Anyway I will look into not using prototypes, after a more close read of Tom Article, thank you for posting the URL.

Re:Some issues

jonasbn on 2003-05-11T18:03:54

Hmmm what do you mean by:

POD is =cut and then immediately continued...

As far as I can see, when
writing the POD below __END__ it does not makes sense to use =cut

unless! =cut is used to close a section?
- do you know if this is this the case?