William F Pokorny <ano### [at] anonymousorg> wrote:

> Aside: What 'sturm' actually does (or not) with any given shape where
> the keyword is supported is very muddy in the code / documentation

What _anything_ actually does is often very muddy in the code / documentation.

It shouldn't take me a week to unravel something like sor because there's a
complete absence of any explanatory / guiding comments.

Some people have this attitude that "Well, it just _expected_ that if you're
using a computer graphics package, that you'd at least know about XYZPDQ...."
But I'd say that from a developer's perspective, the comments ought to be in
there just as part of good coding practice, and not every c++ coder is going to
be a graphics expert or experienced mathematician.  I'm perpetually mystified as
to why someone would be expected to "just figure it out", when someone already
had it all figured out when they wrote the source code.

I would say that if POV-Ray still actually has an active user base, and we want
to actually make the push forward to 4.0 or 5.0 or whatever --- then folks
should take a peek into the code for their favorite object, one that they
understand the CG theory of, or one that they've always been curious about how
it worked - and make some notes about what the source code does and how.

Because even just having a patch version that consists of nothing more than
user-added commentary and theoretical references for all of the various
algorithms would be a big step forward for us, and a giant help to anyone we
might find willing to be a developer.

The comments don't even necessarily have to be IN "the code" - we could just
have a .h, a .cpp, and then an additional .doc or some other extension (.prd Pov
Ray Documentation) text file where everything can get hashed out and unfinished
work can be left as empty outline sections for others to continue work on.

If we had all of that available as an additional "developer documentation"
section of the distribution, then 1. our code would be far more well documented
than it currently is, 2. anyone debugging or adding to the code would be way
ahead of the curve rather than way behind, and 3. all of that theory and
under-the-hood operational stuff would be readily available as a resource to
point to when people on the forum ask the usual questions.

- BE

Post a reply to this message