A little bit of feedback

Hi,

I'm part of the Debian team that packages Linphone, a softphone
written in C++ (formerly in C).  Among its large feature set is the
ability to write Matroska files of video and audio calls.  If you
wonder what library they use for this it might surprise you to learn
that they forked off a version of libmatroska2 about 8 years ago
(nicknamed bcmatroska2).  Since Debian already packages libebml and
libmatroska, and I didn't want to package another implementation only
used by one program, I tried to see if I could just port the Matroska
code in Linphone to libmatroska.  "How hard can it really be?", I
naively thought.  About a weeks later I gave up after sinking
countless hours into this.  What follows is a loose collection of
thoughts and notes I have from this frustrating endeavour in the form
of a barrage of questions.

Why is there no documentation?  The code is barely commented, and most
comments are out of date and worded so incomprehensibly they might
just as well be absent.

Why is the code in such bad state?  I see commented-out code,
inconsistent deprecations of methods, magic numbers and assert() used
everywhere.  Why are you not doing more work on it to improve it?
Have you given up on the code?  Or do you think it doesn't need
improvement?  Why is the code in mkvtoolnix/src/common/ebml.h so much
better?  Why are the templates defined there not part of libebml?  Do
you not realize that if libebml is so inconvenient to use that you
have to essentially write your own convenience library around it, then
it's too inconvenient for everyone else, too?

Why is the test suite in such bad shape?  Why does it not use
accessors for assigning values even though they've existed since
forever?  Why is it so small and not using real data?  For a library
handling binary data that comes with no documentation a well-kept test
suite is the single most important piece of code.

Why is everything named so goofy?  matroska/KaxBlock.h spreads the
task of writing a block across 8(!) different classes, and their names
do not convey in the least what class exists for what purpose (this
BTW was the point where I gave up).

Why is the user expected to also know libebml?  Why is the user
expected to write EBML elements and wrestle with things like cues
manually?  Why does libmatroska not shield him better from these
error-prone details?  Why is there no document object that has sole
ownership of every object added to it?  The current way IMO is a
recipe for double-frees and NULL-dereferences.

Why is libmatroska2 advertised for use by the public?  It has no
releases and experiences API-breaking changes like it's normal.  No
one will ever use that, so why not declare it for internal use only
and hide it away?  Just by having it on the web site you're wasting
people's time forcing them to figure out that they should not use it.

Why is there no coding standard?  The changelog tells me that
libmatroska had embarassing out-of-bounds read and write bugs several
times, but the code still does not use .at() anywhere -- why?  Why is
there no up-to-date TODO file?  Why do you not make it easier for
other people to help you?

I can't wait to hear your answers.

Sincerely,
Dennis Filder
_______________________________________________
Matroska-devel mailing list
[email protected]
https://lists.matroska.org/cgi-bin/mailman/listinfo/matroska-devel
Read Matroska-Devel on GMane: http://dir.gmane.org/gmane.comp.multimedia.matroska.devel