Project / Source Tree Structure

[Zach]

I asked this question before, when I was active on the DBPro Forums and got some interesting responses.
I thought I would also ask here and get your guys' take, as some of you are also professionals who probably use strict standards.

I've always been unsure about the "proper" way to structure my projects, and their source code trees; mostly relating to where I want to store certain information.
In general I like to use Projects, and then split my code up over several files, which hold the code responsible for certain tasks, or "systems". My justification is I want to keep my source code files restricted to a fairly decent size, keep them easy for me to read, and if I want to change something keep them easy to edit. I don't want to waste a lot of time looking through a large source tree for a block of code that I want to change, possibly becoming confused between similar blocks of code (rare problem I guess, but it could happen).

I generally work out of a "Main.pb" file, which houses Xinclude statements, and the main Event Loop. Everything is split off from there, so I would have a source file for the skeleton of my GUI (actual Window / Gadget instantiation and placement) but I may have further includes from that point also, for parts of the GUI that do other things.

My World Editor for my Text RPG for instance, I have my "Windows_GUI" source which builds the actual GUI, but there is also an include file (or will be once I refactor my project for EnableExplicit) which houses a separate Grid Rendering Procedure, and some code related to it, for Rendering the Grid Graphics for my level editing.
---------

I have never used Init() routines, etc in programs before but I know a lot of you do.. Do you generally keep all your variable definitions inside such a Procedure? Do any of you keep them in separate source files? I have often toyed with the idea of dedicated Files for Globals, Constants, Procedures, etc.. But I'm not sure how to strike the right "balance". Obviously I can build Procedures in files related to the systems they control, and obviously any Static/Shared variables can be handled within them.

But on the whole, I'm interested in hearing what other people do, and what they have learned to avoid doing, to prevent problems from cropping up.

[Zach]

Nobody cares to discuss either of the two topics I posted?

I was just curious what other people do, and how important they view their setup

[remi_meier]

I've always been unsure about the "proper" way to structure my projects, and their source code trees; mostly relating to where I want to store certain information.
In general I like to use Projects, and then split my code up over several files, which hold the code responsible for certain tasks, or "systems". My justification is I want to keep my source code files restricted to a fairly decent size, keep them easy for me to read, and if I want to change something keep them easy to edit. I don't want to waste a lot of time looking through a large source tree for a block of code that I want to change, possibly becoming confused between similar blocks of code (rare problem I guess, but it could happen).

That is perfectly fine. You might already use it but
since you didn't mention it, also use directories to
group your files

You can split your code in as many "modules" as
you like (module often = file). Try to reduce Coupling
between modules and increase Cohesion within
a module.

That is all.

I have never used Init() routines, etc in programs before but I know a lot of you do.. Do you generally keep all your variable definitions inside such a Procedure? Do any of you keep them in separate source files? I have often toyed with the idea of dedicated Files for Globals, Constants, Procedures, etc.. But I'm not sure how to strike the right "balance". Obviously I can build Procedures in files related to the systems they control, and obviously any Static/Shared variables can be handled within them.

Try to reduce the use of global variables, as they are
mostly trouble until PB finally supports modules .
I rarely see the point of moving Constants and other
stuff in a separate file, just because they can be
separated. It makes sense, if you make a separate
file for your "public" interface (constants, structures,
procedure-declarations, etc. that are used by other
modules). Like that, one has a nice short summary
of what the module does and what you can use to
control it.

--------------

Those are some pretty general tips, but unfortunately
one learns best by doing it wrong once (or twice).
Those tips can help to remember the mistakes one
has made in the past.

Cheers!
remi

[Zach]

I'm getting around to refactoring my World Editor so I've been putting thought into how I want to organize the source tree.. So I've done some Googling on topics about how people structure their C/C++ projects, etc. I know PB isn't exactly C or C++ but I'm thinking of incorporating some of those standards, hopefully I'm on the right track with that and it will keep things more organized.

I'm implementing the use of Header files (created a new extension *.PBH for PureBasic Header! - would be nice to see it in the IDE one day :p)

I'm thinking I will use the Header files to go with counterparts with the same name (file.PB/file.PBH) and use the Header to declare such things that will be used in that specific file. Mainly Constants, Structures, and Global variables. I know we're supposed to try and avoid Globals when possible but I'm not comfortable with the whole using pointers to pass data between stuff, at times. Structures are kind of iffy because I could have some which are unique to a particular source file, while others may be used globally with different variables and different procedures..

I think a good compromise would be to keep unique structures in the header of a given source file (only because it is used in that specific file), and then maintain a separate sub directory with more globally used structure definitions, each Structure getting its own file. That makes sense to me, because I will be using a lot of structures which are actually built by assembling smaller structures together. So maintaining them will be easier with separate files.

I know in C/C++ people also sometimes put Procedure definitions in headers, but I can't really wrap my head around that one.. A lot of the time I will be definition Procedures in source files, but I may be calling them either in that file, or in the main program loop as part of the program execution logic.

So I'm kind of not sure if I should do any Procedure definitions in the Headers or not, or do certain ones only, etc..

I never thought I would get this obsessed over source organization, but I have already experienced minor annoyances with editing the first build of my Editor so I'm hoping its worth it to waste this much thought and energy in the end.

[Shield]

Hi

You can't really compare PB with C++ since PB dosesn't even support half of the features you
find in those "big" languages. The main feature I'm really missing in PureBasic is the module support.
If PB supported that you could efficiently structure your Code without having to type ridiculously long
names such as "MyEngine_Video_Device_Create" or "MyProject_Windows_Settings_Refresh".
All procedure groups would be strictly separated and by implementing a module file one could access them by
using "using MyEngine\Video" and then calling Device\Create(), for example.

I'm thinking I will use the Header files to go with counterparts with the same name (file.PB/file.PBH) and use the Header to declare such things that will be used in that specific file.

This doesn't make too much sense in PureBasic because PB doesn't make any difference between them.

I know in C/C++ people also sometimes put Procedure definitions in headers, but I can't really wrap my head around that one.

That's how it's done in C++. In C++, every *.cpp file is on its own and not related to other *.cpp files,
they are compiled separately. That's why compiling times of C++ can be kept short, because a module (*.cpp) only
has to be compiled once and doesn't have to be compiled again if there are no changes while in PB the whole
source code has to be processed every time (lucky us that the PureBasic compiler is pretty fast, though!).

You use header files in C++ that define the public interface to that module and if you want to use that module,
you have to include that header file.

But since all those features are not available as of now, we have to find our way around it.
It can be pretty hard and frustrating once a project gets bigger, but it's doable if one keeps discipline
and doesn't start coding hacks because it's a little faster to do so.

Just try not using any global or shared variables at all (or at the most one global variable that is structurized
for providing global program information) and don't write any code outside of procedures except the call for
the main function. This avoids unnecessary side effects and code being executed when it shouldn't.
Also it's a good idea to use EnableExplicit, as you mentionned.


And one more important point I often see programmers doing is, they try to optimize their code during initial development
to get every last microsecond of speed out of it. Don't do that but focus on the program itself and on its structure.
A fast program is good, but it isn't worth a penny if you can't fix bugs because you just can't maintain the source
code anymore. This especially is the case when using assembler. Start optimizing once the program is at a stable point
and optimize time critical sections. It may sound strange, but in average the biggest part of an application is almost
never being executed while only a small part constantly runs...that part has to be optimized.



Good luck with your editor!

[Zach]

I wasn't really trying to compare PB with C/C++, just trying to adopt some of the design standards because I think they would help me personally, to write easy to maintain code. I didn't really have in mind whether or not PB can skip unchanged files during compilation, so much as keeping things simple for me to reference and edit in the future.

I do understand writing function definitions into a header, I just didn't really understand the point when my experience thus far is that most of my logical code seem to be located in my main source file with the event loop. So in that case it doesn't seem to matter to me where I define my Procedures as the whole point of separating my code into smaller files, was to keep related systems stored with their specific code.. I could end up writing nothing but "headers" in that event..

I think a good middle ground I will settle on, is defining variables, constants, and subsystem-specific procedures in header files. More globally accessed data can be done in a "main Header" for the project itself. I just have to make sure the file include system works the way I think it does with regards to my vision.


I honestly don't think I will be able to get by without using globals of some sort, because I just can't "think that way" in terms of where I am with my programming knowledge. I will definitely be using Enable Explicit this time around.

I appreciate your input on the matter, however.

[Zach]

I will also say, although I don't really understand the why's & how's of passing and manipulating data in PB without relying on Globals, I'm not adverse to trying to learn.

So if anyone has any helpful resources/examples to share or link to that deal with the subject specifically in PB, I would like to look at them.

[Kuron]

You have to use what works best for you. Finding what works best for you is usually done the hard way: trial and error.

I prefer a project based IDE, that is what helps me keep organized more than anything else.

[Zach]

I like using Projects too.

I just wished Project support was more "whole" Right now its about worthless to "add files" to your project as that display in the tools panel is little more than a glorified list..

Still have to manually include the files, etc.. PITA

[Kuron]

I don't use Projects with the PB IDE, I don't like the way it is implemented. Projects aside, the PB IDE is the best IDE of any indie programming language out there, IMHO. It is full-featured, but doesn't feel "busy".

I keep things broken down into individual source files (which projects helps keep organized). The breaking down into individual files is where it is up to individual tastes and for me, it can vary between what I am working on. How I would organize something for an app would be much different than how I would organize something for a game. Even different games could have a different organization.