Re: [boost] [review] pqs

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.