[Gnu3dkit-discuss] Development Plan

[Brent Gulanowski]

Fellows,

I will admit right up front that I am a strong believer in design when 
it comes to any complicated system. I know that in the age of Xtreme 
Programming I may be a minority, but I'm going to make a short pitch 
for it (well, short-ish), and maybe some of my suggestions will stick, 
or at least generate discussions. And those of you who do this for a 
living, and don't need me to tell you... well, I just want this stuff 
on record. I'm the last person to school anyone. Phil, I know you're 
working on something design document-esque in your secret laboratory -- 
don't read this if it will interfere!

If GNUstep already has rules about anything here (notably part 3), 
let's please post a link or a FAQ or something on the website, when 
it's possible to do so. Apologies and excuses made...


Suggestions for a Development Plan for GNU 3DKit

Every project can benefit from planning of some sort. I think that G3D 
would benefit primarily from a few particular kinds of documents.

1. Produce a major feature list
This is just an itemization of the features that G3D will offer, from 
general interfaces and platform targets to extensibility and 
third-party hardware/software integration and support. Features should 
be a) ordered by priority and inter-dependency, b) given some kind of 
rating of how much work each will require, and c) grouped in some 
sensible way (i.e.: by component or functional relationship). If each 
major feature (well, those slated for a milestone release, like beta1 
or v1.0 or whatever) was broken into sub-features, that would also be 
good. Then we can look for over-lap and/or conflicts in the 
sub-features. Finding the right granularity for feature specification 
can be a dynamic process.

The flip-side of the feature list is the anti-feature list: what the 
system will not do, ever. Then assumptions about what might or might 
not happen to the code can be made explicit. It's a separate issue if 
they turn out to be wise assumptions.

2. Identify the functional sub-systems
Software just does work that, without computers, people would do. 
People in an organization are always broken down into departments and 
work groups, and I think this metaphor works very well for software 
systems. Especially when you have OOP and multi-threading, 
multi-process, or distributed process models: these are already 
inspired by task management and workload sharing metaphors. Metaphors 
aren't always appropriate, but they can help visualize a system that is 
otherwise very abstract. (I've come to see software development much 
more like people management than like mechanical engineering, except at 
fine granularity.)

If we want to support plug-ins or other modularity (such as a 
modularized renderer), it's helpful to identify how this division in 
the code base will result in a division of task responsibilities. This 
allows programmers to choose what they want to work on and concentrate 
on it, if they desire. It helps newcomers to understand the system, 
including newbies.

3. Specify the code standards
Naming, text formatting, documentation, file layout, repository 
directory structure, and many other things are done quite differently 
by different developers, but the project needs to be consistent. The 
earlier this is specified, the less re-working required.

4. Dependencies
Some are obvious and some aren't. This should be quite simple. What 
environment are we developing in, what language, what tools, what 
dependent libraries and the like. The fact that it's a library takes 
away some of the burden. If we extract the renderer into its own 
module, what's left is probably not far from pure Foundation OpenStep, 
I think, which is great. But even extracted, the renderer will deserve 
some boundaries to be defined around it. For an OpenGL renderer, what 
version of OpenGL? What extensions are we supporting?

5. Construction Plan
The last main thing might be to map out the order that the first set of 
features should be addressed -- the first batch of essential features 
all have the same priority. I'm sure Phil has some idea of what order 
he wants to lay things out, whether it be down-up, top-down, or some 
other approach. I like a kind of top-down iterative blend, myself -- 
sketch the skeleton, then add the internal organs, muscles, nervous 
system, blood vessels, skin, sensory implant junctions, bionic limb 
attachments, kung-fu grip -- you get the idea.

I'd recommend we avoid mixing implementation discussions in the 
development plans, if at all possible. I was just reading the OpenSG 
"Design Document", and it (the document -- not the project, I hope) 
must have really fallen apart while they were writing it, since it's a 
total mishmash of fine detail speculation. It's virtually unreadable. 
They talk about bit mask word sizes in the midst of describing the 
thread synchronization objectives!

Finally, I don't recommend anyone sitting down and single-handedly 
writing some monster document and then presenting it to be argued over 
and finally ignored or made obsolete. I recommend lots of debates on 
the discussion list, and I recommend some kind of format 
standardization to presenting sound bites for features, systems, code 
standards, dependencies and construction plans. I've already submitted 
a few attempts at features/goals -- to the wrong list, I fear. But if 
the design work is modular and collaborative, the discussion list will 
suffice for the documentation of our intentions. I surmise this is why 
Phil made the three distinct mailing lists in the first place.

What I do hope to do, when there is enough design-oriented material on 
the list, is to then assemble something, perhaps even a system to pull 
information out of the list archives dynamically and assemble it into a 
rough draft, which could be edited for clarity and cohesion. If we 
could identify a skeleton for the development plan documentation, like 
with section names or, even better, a numbering system, this data 
mining process would be dramatically simplified. But it's just an idea.

--
Brent Gulanowski                                address@hidden

http://inkubator.idevgames.com/
Working together to make great software.