Re: Documentation of Architecture / Design?

[Douglas A Linhardt]

Han-Wen,

It wouldn't hurt.  But that's not really what I'm approaching.  My point wasn't
so much that the code needs to be cleaned up, but that there should be a web
page / document / something that a developer can refer to to know where to look.

In this example, I couldn't immendiately find VIRTUAL_COPY_CONSTRUCTOR().  It
took me a couple of minutes to remember that there is a /flower directory, and I
found it there.  I'm not suggesting that /flower be removed.  This is just a
minor annoyance that a newbie (I) will learn from.  But it shows that more
direction can be made available to developers.

When you start getting into the macros like (lily-guile.hh):

        #define DECLARE_SCHEME_CALLBACK(NAME,ARGS) \
                static SCM NAME ARGS; \
                static SCM NAME ## _proc

that things really start getting confusing.  When I see the following snippet of
code:
        == Percent_repeat_iterator::constructor_proc

I have a function that hasn't declared (sort of).  And when I see the following
snippet of Scheme code:

        (iterator-ctor . ,Percent_repeat_iterator::constructor)

I'm really confused.  When macro arguments are concatenated to form new tokens,
there should be, at minimum, some comments describing what's being created.  And
having an outside reference that talks about it would give a developer a hint of
what lies ahead.

I like the freedom of coding without worrying about comments, too.  But with a
project this size with multiple volunteer developers in multiple time zones,
some sort of umbrella design document would not be a bad idea.

Doug


On 3/19/2004 3:09 PM, Han-Wen Nienhuys wrote:
> address@hidden writes:
> 
>>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
> 
> 
> would it help if we changed VIRTUAL_COPY_CONSTRUCTOR() , ie going from 
> 
>    VIRTUAL_COPY_CONSTRUCTOR(Base, Name)
> 
> to
> 
>    Base *clone () const { return new Name (*this); }
> 
> ?
>