|Keep It Simple, Stupid|
Re^2: Overloading by Example (small)by tye (Sage)
|on Oct 11, 2007 at 02:44 UTC||Need Help??|
Ah, yes, much better, IMHO. I'd do things slightly differently:
Which can be used like:
I don't find "use strict" nor "use warnings" more than distracting and I didn't like how both your and Ovid's examples conflated the code for a module (that uses overloading) with the code that makes use of that module. Yes, I think that has the potential to confuse people. It also makes the example less useful as a starting point if someone wants code to cut'n'paste.
This example is small enough that the key concepts are easy to spot in it and the distractions are minimal. Of course, it only covers a very small part of overload.pm so other examples are needed. I don't think all of these examples need to be complete and fully self-contained. In fact, I'd find it rather obnoxious if only complete and fully self-contained examples were used.
There are some simple modules where "synopsis" can also serve as "real example" but for many modules a "real example" necessarily makes for a lousy synopsis. It is unfortunate that the boilerplate POD has led to near ubiquitous inclusion of a synopsis but very rare inclusion of real, full examples. I don't think trying to repurpose "synopsis" as "real, full example" is a smart strategy for improving that situation.
Adding more useful and complete, full examples can be beneficial. In the case of overload.pm, such work nearly leads to creation of a full module, and a full module is what is required anyway if someone wants a starting point to just copy. That was the purpose (so I've been told) of Math::BigInt. Perhaps since then it has accumulated too many patches for it to still be ideally suited for that original purpose. So I'm not surprised nor do I find it a deficiency in the documentation that someone wanting to use overload.pm turned to the source code of something like Math::BigInt.