FreeLists / openbeos / [openbeos] Re: Common file-organisation

["Ithamar R. Adema" <ithamar@xxxxxxxxx>]

Hi,

I'm responding to this mail as I'm the Buildmeister for the project.

>I am not yet officially involved in a team, but I want to make some 
suggestions
> nevertheless, if I may:)

_ALL_ comments on this kind of thing is very welcome indeed :-)

>When trying out OpenBeOS yesterday, I saw that the organisation of the
> sub-projects varying widely, which is not surprising but also hinders 
quick testing,
> becoming acquainted with a subproject and could at some point hinder 
optimal
> cooperation.

Agreed. We've discussed this before, and I'm working on a new build/CVS 
setup which will be in CVS _soon_. I'm awaiting prelimenary feedback 
from the team leads on this....

>Following are some observations and inspiration for improvements;):
>
>1. Source is contained in "source", but also in "src"-directories

This has been corrected. There will be only one top source directory, 
containing subdirectories for the different "parts" (kits/addons/
drivers/etc) which will use common naming conventions.

>2. Sometimes there's a Makefile, sometimes a BeIDE-project-file (where 
the
> paths are sometimes incorrect - probably because they are not 
relative), sometimes
> none of the two

Well, in the new setup a Jamfile (see Jam docs on www.perforce.com) is 
required, and makefile's or BeIDE projects _could_ be included as an 
extra "bonus", but will not be used by the main build system (i.e. 
those will be convenience files, just for the developers of that sub-
part of obos).

>3. Testing: it's not always clear what is tested or if the Test-
programm is
> still working - I think the one in the media_kit is a good example: 
it shows the
> expected and then the real output.

For the interface kit there is a generic Unit Testing approach, this 
will be supported in the build system and layed out in a common way in 
the CVS tree.

>4. Documentation: probably the most important and crucial point for 
our
> success: without proper documentation, it will be very hard for new 
members to work
> through the code and understand the concepts, so we should take care 
of that from
> day #1.

Agreed. For code documentation, I cannot stress that using comments in 
the code is a _must_. Also, every "kit" should have some architecture 
documentation as well, which we should standardize in some format as 
well. This will probably be a work-in-progress for the next couple of 
months I'm afraid.

>At least some introductory document should be available for every 
project, even
> - or esp. - in this nascent stage.
>I talked with Jeff Biss about it, and suggested to use doxygen 
throughout the
> entire source. That would be a dream for every new member, and 
minimal effort
> for the author of the code IMO. (of course the OpenBeBook is still 
needed as a
> readable API-description)
>A shining example in this regard is the VM-Preferences-app!

Yep, but we need some decent output, and doxygen is not too good in 
that. Ah well, I'll see if I can get something up as an example for 
discussion, but I think it will be pretty difficult to get this going 
in a way we all (or most) will agree on.

>Hope I could give some positive constructive input, I'll be away the 
next week,
> but I'll reply to all mail afterwards.

As I said, any input on these matters are more then welcome, and I hope 
to fulfill most of your requests in the near future.

Regards,

Ithamar Adema

(OBOS BuildMeister and
OBOS Print Kit Team Lead)