Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 8 Aug 2012 06:57:25 +1000
From:      Peter Jeremy <peter@rulingia.com>
To:        freebsd-numerics@freebsd.org
Subject:   Re: Complex arg-trig functions
Message-ID:  <20120807205725.GA10572@server.rulingia.com>
In-Reply-To: <20120805191954.GA50379@troutmask.apl.washington.edu>
References:  <5017111E.6060003@missouri.edu> <501C361D.4010807@missouri.edu> <20120804165555.X1231@besplex.bde.org> <501D51D7.1020101@missouri.edu> <20120805030609.R3101@besplex.bde.org> <501D9C36.2040207@missouri.edu> <20120805175106.X3574@besplex.bde.org> <501EC015.3000808@missouri.edu> <20120805191954.GA50379@troutmask.apl.washington.edu>

next in thread | previous in thread | raw e-mail | index | archive | help

--qMm9M+Fa2AknHoGS
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On 2012-Aug-05 12:19:54 -0700, Steve Kargl <sgk@troutmask.apl.washington.ed=
u> wrote:
>On Sun, Aug 05, 2012 at 01:48:53PM -0500, Stephen Montgomery-Smith wrote:
>> I plan to respect your style (keep out very lengthy comments), but I=20
>> hope whomever commits my code will respect my style and keep the lengthy=
=20
>> comments.
>
>Essay long comments probably belong in the man page if the essay is
>important to the details of implementation.  Bruce may disagree with
>me.

I also believe that implementation details belong in the code and not
the man page.  The man page should contain information necessary to
use the function: Domain, range, behaviour with exceptional inputs,
accuracy and similar.  Any "unexpected" behaviours as a side-effect of
the implementation can be mentioned under BUGS.  The user shouldn't
need to know that it's implemented by range-reduction to [0 .. e/7]
and then evaluated with an 11th order truncated Chebyshev polynomial
that's had coefficients tweaked by a demon I summoned one evening.

OTOH, the code itself should contain comments explaining what it is
doing - particularly where it is relying on details of the floating
point implementation or the difference between an operation on real
(or complex) numbers and the same operation on float/double/...
numbers.  It's also useful to document why alternative (particularly
"obviously better" alternative) approaches won't work.

--=20
Peter Jeremy

--qMm9M+Fa2AknHoGS
Content-Type: application/pgp-signature

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (FreeBSD)

iEYEARECAAYFAlAhgTUACgkQ/opHv/APuIfeuQCfasUDBNGffA4ztejWbAEPLBCc
WeAAniSA2z7iZZFlr47CYHlYonMtEvBk
=4suN
-----END PGP SIGNATURE-----

--qMm9M+Fa2AknHoGS--



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20120807205725.GA10572>