So I've been working on getting the Windows Functionality Suite 2.0 ready for release in my ample spare time. But I've stumbled upon a problem and I'd like to hear everyone's opinions on it.
The suite has gotten a lot larger than I was expecting it to. It's somewhere around 20 modules, 23 classes and 9 interfaces (excluding items needed for testing and demonstrating). I think at last count I was hovering around the 500 method mark. Along with this explosive growth has come some confusion about how to actually use the Suite. A lot of people don't understand that you are meant to export the items you need and import them into your own project. Furthermore, it's very difficult to tell what items rely on what other items.
Because of these issues, I've been toying with the idea of reorganizing the entire Suite into a collection of projcets where each project showcases a single class or module concept. So there would be a project for the StatusBar, and another one for all the ProcessInformation classes, and another one for window subclassing, etc. This way the user can navigate to the project that fits their needs, see and example that's functional and only does one thing, and use that as a jumping off point to start their own project.
Something like this as a folder structure:
Windows Functionality Suite 2.0
Version History.txt
What's New.txtStatusBar
StatusBar Example.rbp
StatusBar.rbo
Shortcut to WndProcSubclass.rbo
Shortcut to WndProcHelpers.rbo
Documentation.htmlProcesses
ProcessInformation Example.rbp
ProcessInformation.rbo
ModuleInformation.rbo
ThreadInformation.rbo
HeapListInformation.rbo
HeapEntryInformation.rbo
Documentation.rboetc...
However, this still poses some problems (which may not even be problems). For example, when I extracted the StatusBar class, I had external items pointing to the WndProcSubclass interface and WndProcHelpers module. I made these external items because the StatusBar relies on them, but they're not the focus of the project. Furthermore, if I fix a bug in the WndProcHelpers module, I want all the projects that use it to be updated as well. So from a project perspective, this seems to makes sense. But from a navigational standpoint, everything strewn all over the place. The status bar project resides in one folder, but the items it relies on live in other folders.
So there's a few things that I'm wondering about.
- Is the structure of the Windows Functionality Suite confusing enough that the project needs an overhaul?
- If so, what's a decent way to structure things so that it's intuitive for all users but still maintainable for me?
- Is anyone interested in helping me write good documentation for the entire Suite?
I just want to get some opinions on these things before I spend a number of hours restructuring the entire Suite and writing a whole new set of examples. If people think it's time well-spent, then I'm fine with doing it (but it may not be completed until version 2.1 or something). So what's everyone think?
Put it in one big file... isn't that what Basic developers do anyway?
something like... WindowsStuff.bas
(I kid I kid)
LoL, one big file? I think one big function with a lot of gotos is more fitting. :-P
Does the REALbasic Project view support Aliases?
Actually, I think the best approach is the one that REALbasic itself uses -- where everything is included and you just copy the entire folder into your project. With the smart linker, the unused code is not going to be added to the final executable, right? Of course, this is an ideal situation where if REALbasic could compile plugins for REALbasic it would be a perfect fit. Then you distribute the plugin and the REALbasic source code as a seperate file.
Another possibility is a code exporter utility. There is a website that does this on a smaller scale:
http://realbasic.thezaz.com/Athenaeum/
If you need FunctionA; and FunctionA requires FunctionB, then both will be packaged up in the MyModule that is auto-generated and downloaded to your computer.
So if the user needs a StatusBar, it the Utility would export all of the modules required to get the task to work. The great thing about this Utility is that it could also double up as the Documentation browser.
>> Does the REALbasic Project view support Aliases?
Nevermind. I realize now that you are talking about a folder on the disk.
We support external items (items which live on the disk and not internal to any one project), but not aliases as in shortcuts within the same project.
And I thought about the fact that the smart linker takes care of things, but there's a hitch -- it can only take care of them at the link stage, which means all that code needs to be compiled first. It adds quite a bit of time on to the compile time.
That's a nifty little utility -- I had never seen that before! I may have to recommend it (after trying it out, of course).
It is just a website, and will only export source code that is published on the website. I brought it up as a possible solution, though obviously the Windows Functionality Suite is a little more complex than a handful of functions packaged together.
Why not have all the possible classes saved as external items on the disk, then just import the ones you need (as references, of course) into each demo project?
Are they still going to be in some sort of structure on disk? If not, then it's not too much better than having them all in one project since it's still tough to wade thru everything. I suppose I could do something like this:
Windows Functionality Suite 2.0
--Version History.txt
--What's New.txt
--StatusBar
----StatusBar.rbo
----Documentation.html
--Processes
----ProcessInformation.rbo
----ModuleInformation.rbo
----ThreadInformation.rbo
----HeapListInformation.rbo
----HeapEntryInformation.rbo
----Documentation.html
--Examples
----StatusBar Example.rbp
----ProcessInformation Example.rbp
So that all the examples are in one folder, and all the project files are in the folder hierarchy. Then the examples can all have external items pointing back to the file system.