"Beth Jacobson" wrote
Andy Little wrote:
Hi David,
"David A. Greene" wrote 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.
The use of dots and signs is again based on the SI. See for example section 6.1.6 in the 'Guide for the use of the International System of Units'. The +ve sign is redundant but I liked the symmetry and it felt better that leaving it out. and IMO underbars are overused in C++ already.
- 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?
The whole definitions section is obviously problematic. Originally the entities reffered to appeared out of the bottom-up style the library was written in. Trying to explain them to anyone else is not my forte. It is difficult to describe the semantics without them however. I wonder if the library can claim to have the most complicated operation semantics of any C++ library in existence!
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.
Its worth experimenting with surely.
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.
OK.
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.
OK.
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.
OK. I will try to incorporate some bigger examples. Thanks for the comments. regards Andy Little