RE: [boost] Math constants - naming convention?

From: Stewart, Robert (stewart_at_[hidden])
Date: 2001-10-29 12:53:39

From: Paul A. Bristow [mailto:boost_at_[hidden]]

> I'm open to suggestions -
> but how about the following specifying by example and rationale:

As provided, your suggestions are completely arbitrary.  That, of course, is
the reason Jens asked for a defined policy.  You may not agree with
everything I propose below, but it will be a starting point.

> pi  // prefer lower case only - use uppercase only for class names.

I prefer all uppercase for constants.  This helps them stand apart from most
other code.

1. Upper case.
2. Separate words with _.

> half_pi // prefer _ rather than halfPi  (even though I prefer this!)
> quarter_pi // rather than pi_div_4 - looks nicer
> third_pi //
> two_thirds_pi // long but can't have 2/3_pi
> // two_div_three_pi is nasty
> // pi_2_3rd - I don't like much.
> two_pi // cos can't have 2_pi

There's is some prior art using things like pi_2_3rd in binders, but I think
specifying fraction names is clearer, when it's in your native language.
Specifically, if English weren't my native language, I would think pi_2 more
readable than half_pi.  Furthermore, using "PI_" as a prefix for all
fractional values of pi is more readable.

3. Group related values via a prefix, such as "PI_" for all multiples and
fractions of pi.
4. Use numerator then denominator forms with digits to indicate multiples
and fractions.  For example, 1/2 pi would be "PI_1_2" and 2 * pi would be
"PI_2."

The preceding values would thus be:

PI_1_2
PI_1_4
PI_1_3
PI_2_3
PI_2

> log_pi // cos () not allowed in name

It took me a minute to realize that "cos" was supposed to be shorthand for
"because."  I would have recognized "cuz" far sooner as it does not also
refer to "cosine" and is phonetically a better match for "'cause."

Based upon rule 3, above, this would be:

PI_LOG

> sqrt_2 // shorter than sqrt_two and clearer than sqrt2
> // sqrt is commonly used and shoarter than square_root_2

I agree with "sqrt" due to its common usage.  We could establish a list of
common abbreviations rather than try to establish a rule for deriving them
from the natural/mathematics language name.

Thus, we could define "SQRT" for square root, "SQ" for square, "LOG" for
logarithm, "LN" for natural logarithm, etc.

SQRT_2

> sqrt_2_pi // shorter than sqrt_two_pi

PI_SQRT_2

> sqrt_10 // shorter than sqrt_ten

SQRT_10

> cube_root_2 // or what?
> fourth_root_2 // or what?

These suggest using a common root prefix, "ROOT" perhaps, followed by the
number of the root: 3 for cube, 4 for fourth, etc.  Note that there is no
"_" between "ROOT" and the number, since the number indicates which kind of
root rather than a multiplier.

ROOT3_2
ROOT4_2

5. Related operations should have a common prefix.
6. If a numeric value is part of the operation being applied to a value
rather than part of a sequence of operations, that numeric value should be
part of the common prefix.  For example, cube root's prefix is "ROOT3_" not
"ROOT_3_" since the operation is cube root, not 3 * some root.

> pi_sqr // pi * pi or ?

PI_PI?
PI_SQ?

The former is pretty clear that it is the product of pi with itself, given
the earlier treatment of pi.  The latter uses the "SQ" abbreviation for
squaring that I suggested above.  I'm not sure which I like better.

> ln_10 // clearer than ln10, shorter (and clearer) than ln_ten
> // more explicit than log_10 - implies base ten?

Based upon the defined abbreviations, we can say that LOG and LN are
unambiguous.

LN_10

> one_div_sqrt_2 //  shorter than reciprocal_sqrt_2
> // 1_div_sqrt_2 not allowed
> // div more explicit than one_over_sqrt_2 or upon
> two_thirds // longer than two_3rds but clearer?
> one_third // longer but simpler than one_3rd?
> half // clearer than one_div_2
> third // shorter than one_third or one_3rd
> quarter
> five_div_6 // shorter than five_div_six

These are all problematic for the pattern I've established thus far because
there is no neat prefix to put before the numbers.

_1_SQRT_2 // leading underscore since no prefix?
VAL_1_SQRT_2 // some generic prefix?

> two_pow_three_halves // two_pow_three_div_two
> // or two_pow_three_div_2  both might be ambiguous?

This could be turned into a functional arrangement:

POW_2_3_2

but is that 2/3 ** 2 or 2 ** 3/2?

> gamma_third
> gamma_two_thirds

GAMMA_1_3
GAMMA_2_3

> e // short and sweet

E

> e_sqr // e * e  - or e_sqrd? or e_squared?

E_E
E_SQ

> e_cubed // e * e * e

E_3 // e * 3?
E_e3 // suggests e * 10**3
E_POW_3 // no longer than e_cubed and allows for greater consistency

> e_pow_4 // shorter than e_pow_four

E_POW_4

> e_pow_quarter_pi // or e_pow_pi_div_4 is ambiguous?

E_POW_PI_1_4 // combination of previous ideas

> ln_ln_2

LN_LN_2

> minus_ln_ln_2 // can't start with - so use word

MINUS_LN_LN_2
NEG_LN_LN_2

Both of the preceding are English-specific, though I suppose that "NEG"
would be more widely recognized.

> phi // short

PHI

> ln_phi // clearer than lnphi

Reverse the order since the important aspect is phi, not ln():

PHI_LN

> euler // gamma is more likely to be used already.

EULER

> sin_1 // shorter than sine_one
> cos_1 // shorter than cos_one
> sin_0 // or sin_zero?

These all fit the pattern established above -- save for case.

The rules I've specified are probably not complete, but see what you think.

IMPORTANT: The information contained in this email and/or its attachments is
confidential. If you are not the intended recipient, please notify the
sender immediately by reply and immediately delete this message and all its
attachments.  Any review, use, reproduction, disclosure or dissemination of
this message or any attachment by an unintended recipient is strictly
prohibited.  Neither this message nor any attachment is intended as or
should be construed as an offer, solicitation or recommendation to buy or
sell any security or other financial instrument.  Neither the sender, his or
her employer nor any of their respective affiliates makes any warranties as
to the completeness or accuracy of any of the information contained herein
or that this message or any of its attachments is free of viruses.