Boost logo

Boost :

From: Beth Jacobson (bethj_at_[hidden])
Date: 2006-06-07 15:13:05


Andy Little wrote:
> Hi David,
>
> "David A. Greene" wrote
>
>> pqs::velocity::m_div_s - m_per_s? I know this is discussed in
>> the documentation but again, typedefs
>> might be nice to have.
>
> The use of 'div' is meant to stand in for 'divided by' as laid down in 'The
> Guide for the international System of Units' section 7.12.
>
> I'm open to changing the rules by which these typedefs are formed, but I would
> prefer a consensus around one scheme, on grounds that two entities meaning the
> same thing is never a good idea, also bearing in mind that it needs to be
> useable over a wide range of various units as shown above.
>

I find m_per_s much more readable than m_div_s, but as a native English
speaker, both 'per' and 'div' make sense to me. Before stating
categorically that 'per' is preferable, I'd like like to hear from
non-native speakers. They might be comfortable with 'div' but completely
confused by 'per'.

>> Output:
>> 1 kg.m+2.s-2 - What does this mean? It wasn't clear to me when
>> I first saw it. Why not use ^ or ** for power?
>
> Again if there is a consensus I will add it but I guess I figured that it was
> redundant. Does it aid comprehensibility? :
>
> 1 kg.m^+2.s^-2
>
> If it does I am happy to use it.
>

For me, the real bar to comprehensibility is the signs on the exponents.
When I see kg.m+2.s-2, I read it as kg-dot-m plus 2-dot-s minus 2. If it
could it be written like this:

kg.m2_div_s2

it would be much clearer.

>> - What is your evaluation of the documentation?
>>
>> This needs a lot of work. It seems to assume a deep understanding of
>> SI standards and terminology (beyond the unit names and what they
>> mean) and introduces lots of terms itself (abstract_quantity,
>> named_quantity, concrete_quantity, etc.). The presentation is
>> overwhelming.
>
> As discussed before, I think moving the definition of terms to the back of the
> docs will go a good way to solve this.

I disagree. First, David's criticism ("It seems to assume a deep
understanding of SI standards and terminology") doesn't apply only to
the glossary. You can't get through the first paragraph of "Basic
Useage", (shouldn't that be "Usage"?) without encountering "t1_quantity
specification", "concrete_quantities", and "named_quantity". These terms
are going to send a lot of people straight to the definitions page
wherever it's located. Those concepts may be necessary for a complete
understanding of pqs, but I suspect that someone could use the library
in a simple implementation without knowing much about them. If that's
true, they should also be able to read the basic usage section without
encountering that terminology. It might also be helpful to have a
"Physical Quantities Concepts" page, with a concrete example of some
object or system which would illustrate the terms. This would
familiarize readers with the necessary terminology in a straightforward,
easily comprehensible way, reducing their reliance on the definitions page.

Second, the definitions themselves are sometimes rough going. Dimension,
for example, is defined like this: "The dimension of a physical_quantity
is comprised of the powers of each of its base_dimensions."
Physical_quantity quantity is defined as "A measurable physical
phenomenon," and base_dimension as "A simple, measurable and essentially
irreducible physical phenomenon." This means that base_dimension is
really a simple and essentially irreducible physical_quantity (i.e. a
base physical_quantity) which suggests that 'physical_quantity' and
'dimension' are interchangeable, but the definition of dimension
suggests that it's an attribute of physical_quantity having to do with
powers. Even after browsing most of the documentation, including the
definitions page, I still don't really understand the distinction
between dimensions and physical quantities.

The definitions page also describes coherent_unit as "essentially units
designed as part of the SI", and incoherent_unit as "essentially a unit
outside the SI." That being the case, why not just use SI and non-SI, in
place of coherent, and incoherent?

>> I found the colored links to the terms all over the documentation to
>> be distracting. It really interrupted the flow of the text. It would
>> be better to make these links that look like ordinary text but are
>> highlighted/underlined when the cursor moves over them. The links
>> need to be there but they should be less intrusive.
>
> OK. I would guess that is a CSS issue.

I'm not convinced they really do need to be there. The BGL doc, for
example, has an introductory section explaining terms like vertex,
edge, etc., and then uses those terms throughout, without links to
definitions. If the pqs doc did the same, at least with basic terms like
'dimensions', 'units', etc, it would reduce the number of links
enormously. It might be nice to have a standard definition-link style in
the Boost CSS anyway, but I don't think that's essential.

>
>> My suggestion would be
>> to organize the rationale like this:
>
>> * Increases programmer satisfaction and enhances productivity.
>> * Strong type checking enforces dimensional integrity, catching
>> calculation errors at compile time.
>> * Automated unit conversion reduces drudgery.
>> * Self documenting, helps code clarity.
>

I'd leave off the first sentence altogether. When I read that pqs
catches errors, eliminates the need for tedious (and error-prone)
explicit conversions, and improves code clarity, I immediately recognize
those as Very Good Things. I don't need the docs to tell me I'll be more
satisfied and productive as a result.

A few more observations:

The "Introduction to pqs" page is not very helpful. The first thing I
want a library doc to tell me is what the library does and whether it's
worth investigating further. The introduction instead starts out with an
"Overview", which mostly talks about what pqs will eventually do in the
future. While interesting, that doesn't really belong in the
introduction. I'd much rather see something like the 'Description'
section of Fred Bertsch's review announcement post:

"PQS (Physical Quantities System) is designed to replace the use of
floating point types for modelling physical quantities in C++
programs. Advantages include automated dimensional analysis checking,
automatic unit conversions, self documentation of code and uniform
mechanisms for dealing with physical quantities overall, allowing
better interoperability, accuracy and repeatability among engineering,
physics and trade applications."

 From just that one paragraph I've already got a pretty good idea about
whether pqs is going to be useful to me.

A tutorial with a simplified real-world example of a pqs-enabled program
would also be very helpful. The "Getting started" page contains a lot of
code snippets but most of them illustrate only declarations and simple
operations. I realize that encompasses most of what pqs does, but it
would still be nice to see them in different contexts, e.g. std
containers of physical quantities, functions with physical quantities as
parameters, etc. I'd particularly like to see an example of pqs
interoperating with boost.date_time. They'll be a natural combination
for many applications, so it would be nice to see code that converts
between them.


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk