bug#5744: 23.1.92; doc string of `version<' etc.

[Drew Adams]

> > It's not the names that are as important as communicating 
> > what they stand for.
> 
> The best terminology is the one that doesn't need explaining, because
> it speaks for itself.

Obviously. My point was about _finding_ that best terminology.

So far, it's not clear (at least to me) what the behavior is, so suggesting
names is driven partly by ignorance (at least on my part).

You suggested "newer", and then it was pointed out that that was misleading,
since the behavior doesn't correspond to release date. Then you suggested
"higher", but there might be problems with that also, and that doesn't by itself
convey any sense of newness.

If you, who are familiar with the actual behavior, want to just come up with
names on your own, fine - go for it.

But if you want some help, then first express what the comparison _is_, and then
perhaps some of us who are not familiar with the behavior can help you in your
quest for the best terminology.

This technique is nothing new. It is used by those involved with requirements
analysis, documentation, "knowledge acquisition", specification, and other
fields taht involve description and naming.

(That includes much in the domain of software engineering, but it doesn't follow
that all developers take the time to think through the concepts before coming up
with names.)

Yes, the terms in which you think of the concepts do make a difference, I agree.
But you have to start somewhere.

> > I, for instance, don't yet know what exactly is meant. Why 
> > the date of 4.3.4 might be later than 4.4.1, even though the
> > latter is "newer".
> 
> If the 4.3 branch and the 4.4 branch are developed in parallel in some
> project, the chronological order between releases from the two
> branches is unpredictable.

Got it.

> > Try explaining it (the concepts) first, in simple terms. 
> > Then the words (good names) will come.
> 
> These functions compare version strings in their numerical order,

If it is close to a numerical order (e.g. one of the most familiar numerical
orderings) then "greater than" is probably the best first approximation of what
the comparison is.

> with some heuristics sprinkled on top.  It's not easy to explain that in
> simple words, especially since the heuristics can be customized.

If no info about the heuristics is given - no explanation of how a familiar
numerical ordering is modified by them, then stick with "greater than" or a
similar term that suggests numerical order.

If the numerical order used is similar to something like Dewey-decimal ordering,
then it might help to mention that too. I don't know whether that is the case -
I'm just mentioning that that is a particular kind of dotted numerical order
that many people are familiar with. If this is similar to that, then that
similarity could be mentioned as an aid to understanding - if it helps. 

> Finding words that explain themselves will go a long way towards
> resolving this difficulty.

Of course. And vice versa.

With or without the best words, however, the specific behavior (nature of the
ordering) needs to be described to users at some point, somewhere.

It need not all be described in the doc string of a comparison predicate, but
that doc string should at least point to a place where it is described clearly
and completely. That place (or those places) might be the doc string(s) of the
customization option(s) you refer to, for example.

So far in this thread, all that's been described is a numerical order modified
somehow by unspecified heuristics. With only that to go on, I'd suggest sticking
with "greater than".