I’m I the process of moving some of our applications to Subversion from CVS, and while doing so I thought I would take the chance to think about standardizing on a directory structure for our applications/source code. Although it seems like a simple task, it has turned out to be a lot more complicated than I initially thought it would. The main application I work on has many parts, and makes use of many technologies (Flash, ASP.Net, WinForm .Net, C++, Flash Remoting, FlashCom, SQL Server).
Main requirement, the folder structure in theory shouldn’t have much to do with the specific technology. The main reason for this is consistency. When I pick up a part of the application I didn’t work on, I want it to be easy for me to pick up and find everything. Another is for automating builds. It’s easier to automate the building process if you stick to a single standard naming convention/etc.
So to start out, I did some research on what people have standardized on out there. First I started with trying to find some information via google. To my surprise there really wasn’t much discussion on the topic. Everyone pretty much agreed that if you use one convention, use it consistently, but no one had any thought on how a system that consists of many parts would be structured. The problem was that most of the time people deal with only one technology. They are either building a Flash Application, Java application, etc, but didn’t see any mention of what they do when they mix technologies and what happens when development tools don’t play nice with the structure you would like to have.
So, on I went looking at other source. I thought maybe there is a good book out there on the subject, I’m still disollutioned that there’s something I’m missing about this subject, is it really that complicated? So I checked my copy of “Essential CVS” by O’Reilly which is a great reference on CVS but had no discussion on structing your source code. Then I went out to my local bookstore and checked out “Pragmatic Version Control with CVS” (A version for SubVersion is due very soon, I’ll definitely have to buy but it once it is release). This book contained some discussion on good practices when strutting folders/source code repositories. It discussed Projects, Modules, sub-projects, sharing code across Projects, but even with the discussion it had, it seemed geared for if you are sticking to one technology (If you work with CVS and don’t’ feel that comfortable with it yet, pick up this book).
After some reading and giving some thought to our needs, this is what I ended up with, which didn’t end up meeting our needs but lets discuss it a bit further
- Main Root
- README.txt
- GLOSSARY.txt
- BUILDING.txt
- Project
- README.txt
- GLOSSARY.txt
- BUILDING.txt
- Data
- Db
- Doc
- Util
- Src
- Vendor
- Vendorsrc
- Project
- README.txt
- GLOSSARY.txt
- BUILDING.txt
- Data
- Db
- Doc
- Util
- Src
- Vendor
- Vendorsrc
- Library
- README.txt
- GLOSSARY.txt
- BUILDING.txt
- Data
- Db
- Doc
- Util
- Src
- Vendor
- Vendorsrc
How would you structure an appliation made of of multiple Flash interfaces with this tructure in mind?
- MainApplicationRoot
- InterfaceOne
- README.txt : Text file explaining the main goal of this application/interface
- GLOSSARY.txt: Any glossary terms
- BUILDING.txt: Instructoins for building the application. Although ctrl+enter is enough usually it’s good to document the steps and what to do with the swf file after for non-flash savvy developers that might pick up your application to build it
- Build: this is a temp folder that I wouldn’t check into source control, this is where the output of the fla should go. Don’t forget in Flash you can tell it where to output your files, they don’t have to be the same folder as the fla
- Src: In here I would put my PrimalScript pws file, Fla file, and start with my package tree (example com/rewindlife/etc)
- Util: any small tools you might need to deal with the application
- Vendor: Any cool components your application uses (Like cool charting components), etc that you have only in a compiled form.
- Vendorsrc: This is the same as the Vendor except you place the source code. Don’t forget to add this folder to your classpath. Ideally you would have a separate folder for each package/company where you obtained the code. This isn’t always very practical in the Flash world of course as you would have to add several class paths.
- Doc: Where I would place any documentation, specification, etc related to this application
- We don’t have the other folders, Data, DB since our application doesn’t ever (shouldn’t) interface directly with the database
- InterfaceTwo
- Same as interface one
- Library: The purpose of this folder is to store all common items across different applications/interfaces, sometimes I like to call it "Common"
- Src: I would most likely store all my code under here using com/rewindlife/etc
- Doc: if it is a shared set of docs
I like this structure, it works well and I can see myself working with it without too much of a hassle. Now the real question, what happens when you add other technologies and their own development tools into the mix? Well, in this case the book recommends splitting things up most likely using client/server as the devider. Although this sounds great, for our use it didn’t prove good in some instances. It was almost like I had to introduce the concept of technology at times. Splitting things up between Flash/DotNet in the Library folder for example as C# code isn’t shared by Flash. For cases where all your interfaces are built with Flash and the back-end is with a single technology then splitting things up using client/server would work pretty well and that’s the approach I would probably adopt, but for our needs I’m still not satisfied which will be clear why in my next entry
Thats very similiar to how I organize things one thing I did not see though is a place for test code. I usually keep a src and test-src dir.
Great post.
I use a similar structure…
src
deploy
assets
docs
test
I place any unit tests, scratch code, etc. in test. I put all my source in sub folders of source
like flas/ as_classes/ java_classes c++/ etc. These folders have subfolders for vendors. Deploy is where I put my generated builds. I put my build script on the root along with readme, etc. Whatever the case, great topic, organization is a great thing to have.
Greg/Kenny.
Yeah I do have a tests folder. I guess I was leaving that for part II of my post
. Definitly need to have a place for them. I’m actually interested in insight on how you solve the problems when a system contains many parts/technologies. Or do you generally keep the back-end guys away from the front-end guys 
No mention of trunk/branch organization? I keep all of my src directories organized with a trunk and the various branches I’m developing. It makes merging new functionality a snap.
Ben:
I don’t keep a specfic organization for branches. I keep a base folder for the the source tree and I checkout to new folders based on the branch, the naming convention is more what or why the branch is there rather than any special naming convention.
Chafic:
I don’t use subversion but CVS so I don’t know how similiar they are. But in CVS I would have different modules for each “product” and my personal organization would depend on the technology and my involvement in it. Typically I always keep a client and server when working with apps of that type. Within there the “modules” are named by the technology used and then the organization that you mention above comes into play.
Btw, I am not getting notifications for comments even though I chose to. Not sure if this is just my problem. Thats why I didn’t get back sooner.
-Greg
Apologies, notifications are currently down..
Thanks for the feedback. In Subversion from my limited knowledge thus far, any folder can be treated as a module. In general I am really liking Subversion. The big things are being able to re-name items without loosing the history (as you know in cvs you have to remove/add to rename) and the command line client is more user friendly.
Ben I do the same thing Greg mentioned. I check out multiple folders of the same application and rely on CVS to track the rest.
Yea I have seen a lot of noise about subversion lately but I use CVS because of the cross-platform clients (which I am guessing subversion has) but also because most clients prefer it or already use it because of how long it has been around. I definately have it on my todo list to check it out more in depth because I do use my own version checking system when at home for remote client projects that have no version control in place. I offload to a windows server for the backup. Renaming is good it can be a hassle when doing refactoring. One thing that always gets me is forgetting to delete or add a file in cvs causing builds to break for other users. I wonder if there is a way to solve this and if any source control software has come up with a solution. I guess it would be more on the client than the source control to better specify file that aren’t added or no longer exists etc…
Oh one more thing. What do you guys use for your merges when there are conflicts (or if you just want to compare) I use WinMerge works very well. Not sure what other ones are out there.
I use ExamDiff http://www.prestosoft.com/ps.asp?page=edp_examdiff . There’s a freeware version available
Have you used winmerge? if so is there any particular reason you like this better?
Nope haven’t used WinMerge. I’m sure they are very similar. From the screenshots I see that ExamDiff has line numbers down the side, which I like.
I’ve just moved over to Subversion myself. I had some of the same issues in structuring my directories, particularly when it comes to using external libraries. Ideally, you would want to add one (or zero) class paths when you create an FLA for a project.
So here is what I did.
I added global class paths “./as” and “./asext”, which will be used by all FLAs. That is, Flash will look in for folders called “as” and “asext” in the same directory as the FLA. All the project’s own code is checked out into “as” and other libraries are in “asext”, which I shouldn’t have to edit in that working copy. I added a property to the parent directory “svn:externals asext”, which means that SVN will know it has to keep that directory updated, even if it is from a completely different part of the repository (or even a different repository altogether).
This is the really cool part of SVN; it makes no distrinction between directories and modules. You can check out a directory of a project, without checking out the entire thing. So my externals directory can contain just the ActionScript package folders of external libraries, and even partial packages (since most packages are in “com”). Since the dependency is created with an SVN property, any developer that checks out the project for the first time will get all the other libraries sent over too.
I’ve had this setup for about a week or so, and its working out pretty well.
One problem that I’ve had is integrating SVN into PrimalScript. So far I’ve had no luck; have you tried that yet?
On Pragmatic Programmers SVN book, it’s now available. I ordered it on Thursday and PDF was released and sent to me on Saturday. Buy the book here:
http://www.pragmaticprogrammer.com/titles/svn/
TortoiseSVN is really good SVN interface on Windows, you can do everything necessary with it:
http://tortoisesvn.tigris.org/
And for diffing/merging I think nothing can beat Araxis Merge:
http://www.araxis.com/
I haven’t tried to integrate SVN with PrimalScript. One thing I like with SVN is its command line interface. So I use that
I ordered the SVN book today actually, Bought it from http://www.bamm.com, was 1/3 off or something. Looking forward to when it comes in.
Thanks for the reccomendation of Araxis. I’ll have to check it out