Quality of XML comments.

Mar 12, 2013 at 5:39 PM
Hi, I'm new to this library. I have my own SpatialVector class but I need to rotate around an axis so before beginning to write my own matrix type, I thought I'd look at MathNet and possibly replacing my vector with one from this lib, if its better.

The problem I have hit immediately is that I can't even instantiate one. The XML documentation/comments on the SparseVector (sparse? I guess this is the right choice for vectors in Euclidian space) are useless.

You can look at this comment as critical feedback. In my own APIs, and from reading and studying framework design, a smooth and gradual on-ramp is the key to adoption and success. This means massive user-empathy, choosing self-explanatory variable names and going over the top with XML comments. The result is falling into the pit of success, i.e. make it hard to do the wrong thing.

You might think I'm being harsh, considering the community effort put in for no financial reward, but this is my point. If you put all that effort in, surely you want people to take to it immediately.

Most internet people have no patience and just move on. They're in "trying to get something done" mode. They don't care about MathNet, unless it saves the day. They didn't pay for it, so they have no incentive to invest time learning it.

So, specifically, the constructor overloads on Double.SparseVector have these signature and comment combinations:

IList<double> array: "The array to create this vector from."

It's not an array and what should it contain? i, j, k unit vectors? How many? Can I make 11-dimension vectors?

int size: "the size of the vector."

Like, the magnitude? Size is meaningless. Is this the dimensions it has?

value: "the value to set each element to."

So maybe the size is the dimension count, but how does that work when there's only one value variable?

What about some common scenario constructors or subclasses, most people will be using 2D and 3D vectors.

~Luke
Coordinator
Mar 13, 2013 at 10:59 AM
Edited Mar 13, 2013 at 11:09 AM
No worries, you're preaching to the choir. We're trying to follow the very same API design approach (which is actually unusual for math libraries), although it seems there is still quite some room for improvement. Such feedback is therefore very welcome!

Double.SparseVector: I agree, the XML comments on the constructors are not really helping, and the name "size" is unfortunate. We should work on that.


Then, concerning the specific case (not the general feedback about our lacking XML docs in general):

There also seems to be a context mismatch here: It seems to me you're looking for spatial/geometric/mechanical vectors and (transformation) matrices, while our matrix and vector types are really about linear algebra (that's why they are in the LinearAlgebra namespace). The usage scenarios, expectations and even the "language" in these two contexts are quite different, but also the way they would be implemented. Maybe we should point this out more clearly. While I'd love to go into the spatial world in the future (think "Math.NET Spatial"), our current matrix and vector types are really focusing on the linear algebra scenario and are not well suited for geometry (they don't even provide a cross-product, there's no notion of affine transformations or a quaternion, they would perform badly, etc.)

As such, in the linear algebra context:
  • Vector and matrix dimensions are arbitrary, so providing an array or list would be an obvious and expected choice for construction.
  • Vectors of size 2 or 3 would not be specially dominant. Nevertheless, we could still consider adding a constructor accepting a params-array for simpler usage.
  • I'd consider any usage of sparse vectors with a dimension less than 50 as a bug (dense vectors should be used instead).
  • I'd expect the API to be optimized for common linear algebra scenarios, including matrix decompositions, working with linear systems and generic least squares problems.
While on the other hand, in the spatial context:
  • Dimensions should be hard-coded to 2 or 3, maybe also 4. No arrays would be used at all.
  • All operations would be unfolded and heavily optimized for these dimensions. No loops would be needed.
  • I'd expect explicit x-y-z style constructors, but also e.g. by length and direction, maybe even using angles.
  • I'd expect the API to be optimized for geometry (and maybe mechanics).
  • There could also be some basic support for coordinate systems, mapping, physics or gaming scenarios.
Thanks,
Christoph
Marked as answer by cdrnet on 10/3/2013 at 5:45 PM
Mar 15, 2013 at 11:26 AM
Edited Mar 15, 2013 at 11:27 AM
Hi Christophe,

Thanks for understanding and following-up with a detailed response. I'm not a mathematician, just a man with a problem to solve, and so I can't comment on your linear algebra points above, but the second set regarding spatial context seem very sensible.

Approaching my problem from the maths books, I needed to rotate a vector. Vectors and rotation transforms falling under linear algebra in the books is the reason I homed-in on the types in the LinearAlgebra namespace.

Anyway, I don't think either of use have the time to sit and chat all day, and I'm pleased with your dedication to the usability cause. Thanks for your time, good luck with the project and I have it on my radar now.

a+

Luke