[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index][Thread Index][Top&Search][Original]
Re: RFC: version.pm qv() confusion
Gisle Aas wrote:
>> The problem is, I don't know what to call it? None of the following
>> are ideal:
>>
>> nv()
>> vv()
>> newv()
>>
>> Anyone what to venture an opinion?
>
> Don't add any new shortcuts. People that can't be bothered to write
> version->new() ought to continue to use the good old string/float
> version numbers.
When a user interface explaination says "the user should do X", that's a red
flag. Another is anything along the lines of "if the user is too lazy to do
X...". The first tries to control what's in the user's head. The other
assigns negative emotions to the user's actions justifying a punitive stance
from the interface designer.
Finally, when the fix for "the users are using function X wrong" is "put in a
new function that does what the users want" that's only fixing part of the
problem. You still need to address why users got function X confused in the
first place.
I don't think the real problem is people being too lazy to write
version->new(). The real problem is people think qv() is a shortcut to
version->new(), and the docs back it up.
There is a broken user model about what version->new() and qv() do. Namely,
that they're identical. How does this idea get into the user's head? Two
reasons. The first is users think versions are simple, and they should be!
1.2 and 1.2.0 should be equivalent, but they're not according to version.pm.
Users are coming to version.pm with this existing user model about versions in
their heads, and version.pm must actively alter it.
Second, it's like those old corny drug ads where the child yells at the parent
"I learned it from watching you!" Humans look for symmetry and simplicity,
and they'll read documentation with this slant in mind. The version.pm
documentation backs it up. Look at the SYNOPSIS.
use version;
$version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1
print $version; # v12.2.1
print $version->numify; # 12.002001
if ( $version gt "12.2" ) # true
$alphaver = version->new("1.02_03"); # must be quoted!
print $alphaver; # 1.02_0300
print $alphaver->is_alpha(); # true
$ver = qv("1.2.0"); # v1.2.0
$perlver = version->new(5.005_03); # must not be quoted!
print $perlver; # 5.005030
There's qv() in with all those version->new() calls with no special comment.
Must be a shortcut! That's about as far as a user is likely to get in the
documentation. Maybe they go onto page two, "BEST PRACTICES".
If you intend to use "Extended Versions", you are strongly
encouraged to use the qv() operator with a quoted term, e.g.:
use version; our $VERSION = qv("1.2.3");
Use qv(). Ok! Nothing else in the BEST PRACTICES section of relevance. And
later in the qv() docs...
o qv()
An alternate way to create a new version object is through the
exported qv() sub... It is the best way to initialize a short
version without triggering the floating point interpretation.
For example:
$v1 = qv(1.2); # 1.2.0
$v2 = qv("1.2"); # also 1.2.0
Alternate to version->new and it's the best way to do a float version. Look,
there's examples right there using qv() to do a decimal version. Must be ok.
And so on.
To fix this, these changes need to be made to the docs.
* Put a note in the SYNOPSIS about qv().
Make it clear on page one that there's a difference between version->new and qv().
The SYNOPSIS is as far as many users get. If the SYNOPSIS looks sensible
there's no need to wade through the documentation. Most of the docs is of no
relevance [1] to someone who just wants to write down a version number.
* Put a section in BEST PRACTICES about it.
If this is just a big problem there should be a section in BEST PRACTICES
about it. Page two. When do you use version->new() and when do you use qv()?
What would be handy is a side-by-side table of qv() vs version->new() with
various inputs.
* Put a section in BEST PRACTICES about comparing X.Y to X.Y.Z.
Which should say one word, "Don't", and then go into detail.
* Put a section in BEST PRACTICES about moving from X.Y to X.Y.Z.
Which should say to increment X to avoid the 1.94 -> 1.95.0 problem.
* Clarify the qv() docs.
The first line of the qv() docs suggests that it's a shortcut for
version->new(). Clarify that it is not, what it does differently from
version->new() and when and why to use it.
* Eliminate all the bad examples.
There's *a lot* of examples showing qv() with X.Y versions. If that's a bad
idea, replace them with good practices. Sweep through all the code in the
docs and replace all the questionable stuff with good examples. Any
deliberately bad examples should have a comment "# BAD" above it to prevent
skimming users from copying it accidentally.
But this is not the root cause of the problem, it's just putting warning signs
around it. The root cause, and I now you don't want to hear it John but I
have to say it, is that 1.2 is not equivalent to 1.2.0 and that 1.2 is greater
than 1.3.0. If you don't know the historical context of Perl versions, and
you can't expect users to, that's nonsense and will continue to surprise
users. Fixing it to be in line with user expectations is the only way to make
the problem go away for good. If it can't be fixed, it should be addressed
directly and clearly and early in the documentation. Users will continue to
make the same mistakes until it is.
Here's a start, I just noticed this in the very first SYNOPSIS example.
use version;
$version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1
print $version; # v12.2.1
print $version->numify; # 12.002001
if ( $version gt "12.2" ) # true
That last statement is not true by my testing. I don't know if it's supposed
to be, but it's reinforcing the notion that 12.2 == 12.2.0 right there on page
one.
Finally, any external examples using version should be checked to see if
they're encouraging the same bad habits.
As a final thought, maybe a perlcritic check for questionable uses of qv()
would be handy?
That's my quick analysis of the version.pm problem. Fix the docs and I think
you'll find the problem will slowly thin out as the new information gets
disseminated. Sure beats yelling at users one by one on p5p. ;P
[1] Or at least shouldn't be. I realize it's a complex issue.
--
Defender of Lexical Encapsulation
- Follow-Ups from:
-
"David Golden" <xdaveg@gmail.com>
[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index][Thread Index][Top&Search][Original]