Re: [boost] [QVM] Boost.QVM formal review is ongoing

Subject: Re: [boost] [QVM] Boost.QVM formal review is ongoing
From: Rainer Deyke (rainerd_at_[hidden])
Date: 2015-12-17 11:37:29

This is my formal review of Boost.QVM.

My name is Rainer Deyke.  I have a fair amount of experience in the
problem domain.  It's not exactly my area of specialization, but I have
written similar code, I have worked with similar libraries (glm in
particular), and I have written GLSL shaders that work with vectors and
matrices.

I believe that Boost.QVM should be accepted into Boost on these conditions:

The library in general should be made more verbose.  The terseness is
not a problem when writing code, but it can greatly hinder readability,
especially when reading code written by someone else where the reader is
not familiar with Boost.QVM.  It also makes it harder to search through
both code and documentation.  The various instances of 'q', 'v', and 'm'
should at least be expanded to 'quat', 'vec', and 'mat', if not fully
spelled out.

The documentation should be improved.  In particular:
  - The tutorial section should start with some simple uses of the library.
  - It's not immediately obvious which functions are classified as
"operations" and which are "view proxies".  Usually this can be regarded
as an implementation detail.  Either the distinction should be made
clear (e.g. "all unary operations return view proxies"), or the
operations and view proxies should be grouped together in the documentation.

I also strongly feel that the comma operator should be replaced with
function call syntax, i.e. X(v) instead of (v,X).  However, I realize
that this is bikeshedding on my part, so I am not making this a
condition of Boost.QVM's acceptance into Boost.

> - What is your evaluation of the library's:
>   * Design

Seems solid.  I especially like the use of view proxies to lazily
evaluate certain operations.

>   * Implementation

I've only taken a cursory look, but I haven't noticed any particular
problems.

>   * Documentation

Could use more work, see above.

>   * Tests

I've only taken a cursory look, but it looks reasonably complete.

>   * Usefulness

Very useful.  I intend to start using this in production code the moment
it appears in an official Boost release.

> - Did you attempt to use the library? If so:

No.

> - How much effort did you put into your evaluation of the review?

A few hours of work.

-- 
Rainer Deyke (rainerd_at_[hidden])