Style for Function Descriptions

["Dennis E. Hamilton" <dennis.hamilton@acm.org>]

I notice that there is distracting variation among the ways that the
individual spreadsheet functions are described.  Although there is a common
structure that is followed, there are inconsistent variations that make
people work too hard in determining what these are and how they might be
different from others.

I do think we should have a strongly-followed format and style for the
content.  We might want to work this up on a wiki page or somewhere.  It
should also be described somewhere in the text (perhaps in section 1 where
such things might be consolidated) so that folks understand what to expect
and also how to review or following of the style.

 - Dennis

MATTERS TO CONSIDER

There are a number of things that need to be dealt with:

1. Organization of the description (what the parts are and what goes in them
and what they are intended to provide).

2. Use and naming of (pseudo-)datatypes and of parameters (or arguments, but
I am a fan of parameter, although what we must do is be consistent)
terminology, naming, and typography.  (E.g., italicize parameter names
everywhere, don't capitalize first letters, etc., always use proper
(capitalized) nouns for datatypes, and so on)  Also, it should be clear when
additional parameters are allowed beyond the basic two (e.g., when a series
of parameters is permitted) and when there is no such provision.

3. Have the top summary description not be the normative description but
just an aid in figuring out what the function is as something helpful beyond
the compact name that is used for the function in formulas.

4. Move the summary of what the parameter values are used to represent up
with the syntax, result type (and summary description) so that those aspects
are presented together.

5. With regard to hard constraints, indicate the kind of error a violation
is.

6. Say something explicit about errors that arise, errors that are
propagated (not always a wonderful idea), and errors that are absorbed.
There are probably simple cases to be identified in a general place (as is
done somewhat already) with reference to the applicable case, with any
qualifications, from the individual function descriptions.

7. Eliminate the use of the term "Semantics."  Syntax might be tolerable for
the Function Prototype, although Format or Form is probably a better term
for format of an use of the function.  But "Semantics" is not helpful when a
plain-language notion will serve. Definition or Description is a better
title, and there should be an accurate description about the conditions that
the function result satisfies, in terms of the provided argument values and
any influential settings that figure in what the function is.  

8. Descriptions of what the function determines should use descriptive
language, not procedural language.  For example, it is descriptive to say
that the mathematical floor of a non-complex number, x, is the largest
integer not greater than x.  However, before one says that is also the
result of OpenFormula FLOOR(Number x), there must be some statement
concerning cases where Number value x is not in range for
exactly-representable integers. Implementation-defined and
Implementation-dependent qualify as explicitly statements, but there might
be an agreeable definite result to have agreement on.

9. We should be careful to distinguish between when we are defining one
function in terms of the computation of another *computation* versus in
terms of another mathematical function.   We might need more typographical
convention for this (e.g., as when I use x for the parameter value and for a
mathematical variable having that value, or when I used lower-case "floor"
as opposed to "FLOOR" although there is also mathematical symbology for the
floor function).  

10. It is peculiar to have a mathematical formula that has
spreadsheet-function names being used as if it is a mathematical function
and we should avoid that.  It is one thing to observe that floor(-x) = -
ceil(x), which is always true for non-complex x, but it might not be true to
say that FLOOR(-x) = - CEIL(x) because of Number representation edge cases
(and I made that mistake on this list somewhere).  Similarly, while we can
say with confidence that -1 < tanh(x) < 1, that might not apply for
TANH(Number x) unless we are prepared to require that the computation be
that tight, with computational rounding to 1 or -1 not permitted.  (If
rounding to magnitude 1 is permitted for the delivered computational result,
there are consequences for ATANH(Number x) edge cases too.  It is rather
unexpected for ATANH(TANH(x)) to ever fail for Number x not an error
result.)  

9. With regard to results, we must always be clear that we are talking about
computational results, however represented, and not how the
computationally-represented values might be presented as rounded and
otherwise-formatted results (e.g., derived from but different than the
computed value and even the computed value as preserved as a cell value).
In specifying the computational result, we must be careful about what we
mean by the type of the result as opposed to what might be required if that
result is represented in a cell that is then presented in some manner.  

10. For example, The use of Currency as a result type is a little bothersome
in that regard, because it is not clear that the result should be somehow
always confined to actual values that are available in a given currency.
(That is, nothing smaller than a penny for $USD.)  That's not too hard to
deal with but there might be intermediate values (all coupon payments
assumed to be already made, for example) for which the presumption of some
currency rules is problematic when currency rules are applicable in how
those intermediate values are established in practice.

I'm sure there are more.  

-----Original Message-----
From: Andreas J. Guelzow [mailto:aguelzow@pyrshep.ca] 
http://lists.oasis-open.org/archives/office-formula/200912/msg00155.html
Sent: Wednesday, December 23, 2009 18:46
To: office-formula@lists.oasis-open.org
Subject: Re: [office-formula] MIRR

On Wed, 2009-12-23 at 19:40 -0500, Patrick Durusau wrote:
http://lists.oasis-open.org/archives/office-formula/200912/msg00152.html
> Andreas,
> 
> Andreas J. Guelzow wrote:
http://lists.oasis-open.org/archives/office-formula/200912/msg00146.html
> > I'll pick this one but the same applies to most other comments of this
> > type:
> >
> > On Wed, 2009-12-23 at 11:07 -0500, Patrick Durusau wrote:
http://lists.oasis-open.org/archives/office-formula/200912/msg00141.html
> >   
> >> MIRR lacks parameters, at least as we define them for other functions.
> >>
> >>     
> >
> > In my copy, parameters are specified:
> > MIRR( Array Values ; Number Investment ; Number ReinvestRate )
> >
> > Stating that "Values" are a bunch of values, "Investment" is the
> > investment rate and blablabla doesn't mean anything and doesn't define
> > anything either.
> >
> > This function is defined by given a specific formula (with the little
> > problem that the lower case n and upper case N should be the same). I
> > would hope that all function definitions/descriptions would look like
> > the current 5.12.28 MIRR.
> >
> >   
> Well, but my point was that rather than having the listing of parameters 
> that you object to, MIRR instead has:
> 
> > Values is a series of periodic income (positive values) and payments 
> > (negative values) at regular intervals (text and empty cells are 
> > ignored). Investment is the rate of interest of the payments (negative 
> > values); ReinvestRate is the rate of interest of the reinvestment 
> > (positive values).
> >
> It just reports them in a paragraph of prose.
>
> Personally I don't find than any more useful than listing them in the 
> other style.


I would prefer to delete those paragraphs to. Unfortunately they also
appear elsewhere, for example:

"COMBIN returns the binomial coefficient, which is the number of
different R-length sets that can be selected from N items. Since they
are sets, order in the sets is not relevant. The parameters are
truncated (using INT) before use. For example, if a jar contains five
marbles, each one a distinct color, the number of different three-marble
groups COMBIN(5;3) = 10. The result is
(formula omitted)
Note that if order is important, use PERMUT instead."

I find that completely pointless. The formula alone should suffice.
(Note that COMBIN calculates lots of other things too.)

Andreas


-- 
Andreas J. Guelzow <aguelzow@pyrshep.ca>


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php