Re: Documentation of Architecture / Design?

[Han-Wen Nienhuys]

address@hidden writes:
> First, let me say that I consider myself a pretty good programmer (I survived
> the layoffs at Lucent over the last few years ;) ).  I am very well versed in
> C++, so of course, that's where I gravitate first when I look at Lilypond 
> code.
>  I am able to follow the Scheme code after reading the R5R, and I have been 
> able
> to successfully implement some Scheme hacks as I investigate my autochange
> tuning feature.  I have yet to look at Python, but I may have to learn that 
> too,
> if that's the way the project is headed (although I'm not looking forward to 
> it).

We're not headed to Python, but I can recommend learning it
anyway. Programming in Python is a very enjoyable pastime.

> The problem isn't necessarily that I can't find the answers to my questions, 
> but
> that it can take hours of searching through code to find a particular
> design-level fact.  And by that time, I've pushed and popped so many elements 
> on
> my mental stack, that I can't remember how I got there and what I already
> dismissed as dead ends.  A roadmap would direct a developer's search for
> appropriate code and reduce the learning curve.

OK. (I hope you do know about etags or ctags?)

> Probably the biggest things that threw me are the C++ member functions that 
> are
> declared/defined through macros.  It's really annoying when a member function 
> is
> not directly declared in the class or one of its ancestors, but in a macro in
> some other file completely.  Some documentation of these macros and the "for
> free" functions that we get would be nice.

I've rewritten the comment of smobs.hh in CVS. Hope that it helps.

> Also, I get lost figuring out what environment the code I'm looking at is in
> when it executes.  I found both the C++ and Scheme autochange code.  Then I 
> was
> trying to figure out where the code got called from.  I finally figured out 
> that
> the Scheme procedure was called before the C++ iterator code, but it took me a
> while to figure that out, and I still didn't know who did the calling in the
> first place.  I only know a little bit about Flex and Bison, so reading those
> files helped only a little bit.

GDB can be of help here. Set a breakpoint in C++, and run. When you
hit the breakpoint, do a backtrace. You can inspect Scheme objects
along the way by doing

  p ly_display_scm(obj)

this will display OBJ through GUILE.

-- 

 Han-Wen Nienhuys   |   address@hidden   |   http://www.xs4all.nl/~hanwen