利用者:Double dose

Classes, Structs, Functions, and Variables: specifications, diagrams, and test cases
The following is a start for my understanding of the Blender Source Code for Blender Version 2.5 alpha 2.

My Vision:

I think it would help me and many others tremendously to have some detailed specifications of the all the functions of the source code (organized and linked well of course). If I create enough, I'd like to add those detailed specifications of each function to the blender dev wiki. In the future, test cases and links to these specifications could be added, helping with testing and getting the versions of blender churned out faster.

I'd like to eventually see two sections added on:
http://wiki.blender.org/index.php/Dev:Source/Architecture
The two sections would probably be called: "Code Specifications and Diagrams" and "Code Test Cases"

Test Cases simply allow the developer, new or experienced, to not have to develop several tests on the fly when a piece of code is changed (possibly missing a crucial test that will come back to haunt). Though I've discussed Reference and Test Cases, one thing I'm especially interested in remains. I would really like to see more tutorials and/or tours of the code. They help new developers learn the inner workings faster.

I have an idea of what a "good code tutorial" should be. Before defining the idea, I describe two basic requirements. First, I'd assume the tutoree can get the source compiled (allowing debugging and the tutoree to visualize the code's flow, and Blender wiki already has several tutorials on doing that. Second, after knowledge of compiling is achieved, there would be several areas of Blender functionality that the user could choose from, an architectural organization to the tutorials. Now. On to my definition of a good tutorial. Once a functionality area (say the blender api) is chosen, the user would then be instructed on some changes to the code, given some script to run before and after the change, and allowed to see the changes to the system first hand. This type of tutorial is similar to the ones on using blender, except it is for new blender programmers instead of artists.

Thankfully, there are tutorials similar to what I'm describing. So why again am I discussing this today 4/4/2010? Because I want to see more.

I'm notoriously ambitious and optimistic, but Blender already has such strong community support, available information, visual feedback, and freedom to choose a contribution/project area. If we added "quick learning curve" to the list, Blender might be one of the best learning aids for beginning programmers, especially those seeking a degree! And if the documentation is successful at adding structure and organisation, Blender will surely grow in capabilities, on an exponential scale!

My Plan:

1. Get a pipeline for documentation.
2. Get the Classes, Strucs, and Functions listed and linked.
3. Fill in as many details as possible on the specifications.
4. Add diagrams to many functions.
5. Develop Test Case References.
6. Develop tour tutorials (when I find the time, because at this point, I should know enough about the code to start contributing some major features that I've had in mind.)

Concerns:

• How does a program like Cmake/scons affect the project files' locations or code for that matter?

Closing note:

If anyone would like to contribute to foreseen specifications, I'm sure I'm going to need help in understanding them. Please just keep in mind that I keep strong visions for my projects, so I might edit your contribution. Disscussion would probably be the place to start a contribution. That said, I make mistakes and I'm sure I have much to learn as I'm an undergrad senior in Computer Science as of 2010. Peace.

Reference:

Code Documentation Methods
Specifications