Suggestions? I'm not sure I can make any concrete
suggestions that I feel very strongly about. The header vs. .c
file issue is just a minor problem of initial friction (I looked
for where something was being done, and it took me a while to
realize that all the logic I was interested in was in a header
file. It's an unusual choice, and not what I would expect.) Once
you know where to find the code, it's not hard to understand,
but there's some initial confusion where it seems like the code
isn't actually there.
A walkthrough is always nice to have, but like all
documentation it would have to be maintained when the design
changes. This rarely happens in practice, I find. It's better
to write the code in a way that's readable and allows
maintainers to discover where things are without having to
grep through the entire code base for things that might be
relevant.
The main source of confusion for me was how the entire
airborne code is essentially compiled from the various XML
files, but there's nothing in the XML files themselves that
can give you an idea of how the resulting code is going to be
structured. This is unlike any compiled system I've seen
before, and feels more like a software framework, where user
code fits into multiple interfaces and interacts with them in
ways that may or may not be well documented - this kind of
design tends to be difficult to understand, unless you have a
thorough understanding of the entire system. There's just no
obvious entry point.
Having said all that, I don't feel I have any good ideas on
how to make things better. Not even if I were going to start
from scratch (which no one here would want to do, and I'm
obviously not advocating for that.) The goals of the project
are certainly ambitious, and it attempts to solve a whole
bunch of complicated problems, so it's not surprising that the
solution is complicated. I guess I'm just frustrated at HOW
complicated it is...