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.