hugin-devs team mailing list archive

[KFJ <789442@xxxxxxxxxxxxxxxxxx>]

> The biggest advantage I see in a carefully crafted clean API is human:
> the more understandable and simple the API, the more users it will attract.

Quite right - programmers are also users. A clean API might attract more
people to hugin development. Currently I see the code bloated with
several different access patterns, reflecting the move from C to C++ and
the passing of time. And I see it mainly devoid of comments, apart from
the odd sprinkle of cryptic comments which mostly make sense for the
original author (ot the frustrated maintainer). I didn't know any better
than to emulate this undesirable pattern in hsi, but I didn't enjoy
doing it. What came out is as unattractive in Python as the wrapped code
is in C++. Never mind the design seems to be well thought out, it's hard
to figure out.

The question is how we can extract the knowledge and thought that went
into the design of the project. Obviously the easiest would be for the
authors to document it. I know from experience how easily one is just
content with a bit of code running and quite 'forgets' to document it
because there is so much else to do (which is more fun, or more urgent)
- and when documenting code, it's easy to be too close to what one has
just coded, so it's hard to decipher later on, even by oneself. But it
has to be done, otherwise the code looses value quickly as the project
moves on, or puts a spanner in the works when it fails to be easily
extended, modified, refactured.

-- 
You received this bug notification because you are a member of Hugin
Developers, which is subscribed to Hugin.
https://bugs.launchpad.net/bugs/789442

Title:
  2011.2: formalize API/headers immutability

Status in Hugin - Panorama Tools GUI:
  New

Bug description:
  In the words of Kay:
  > Scripts are really lightweight. If you look at woa, which is really a
  > large script, it's merely 59K. The real load currently is the hsi
  > module, _hsi.so, weighing in at 8.1M. I wouldn't worry about bloat
  > from scripts. And if you worry about bloat, defining a clean API for
  > hugin, so that hsi can wrap what's really needed - and wanted - to be
  > accessible by everyone instead of near enough everything declared in a
  > bunch of headers never meant for the wider public. I'd estimate
  > _hsi.so could shrink to a quarter or so.
  >
  > A proper API specification would also be a remedy against scripts
  > breaking as soon as the headers in question are modified in an
  > incompatible way - and that's quickly done: change a call signature or
  > type name and swig will duly wrap it to keep the module consistent
  > with the C++ code, and hsi code using the old names/signatures breaks
  > and has to be adapted. Resulting in lots of frustrated users and
  > script-writers (and support load: 'xyz.py does not work any more' -
  > 'are you using hsi 5886.X already?' ...)

  Currently the Python wrapper is
  a) bloated and
  b) very fragile.

  The negative consequences from (a) are an API that is complex  and not
  as user-friendly as it could be.  I am not worried about the extra 8M
  disk space or download-bandwidth.

  The negative consequences from (b) are far worse.  As described above,
  a small change in the wrapped headers can lead to incompatibilities
  between the hsi module and the body of scripts available.

  One potential solution is to "guarantee" (best effort) a stable API
  only on releases (odd version numbers) of Hugin.  This means that
  users on the bleeding edge may experience the occasional frustration;
  and that with every release the whole body of plug ins would need to
  be tested against that release to determine if the API breaks or not.

  The cleaner solution to both (a) and (b) is to define a fine grained,
  clean, lean and streamlined API, but I am afraid that the task is way
  too big for a  release and is better left for a major project, e.g. a
  Google Summer of Code project.