How to Organize a Source Tree?

code-organizationsolo-development

I am an individual developer working, largely, on web-projects (W/LAMP) and, at times, on C/C++ (non-GUI) projects of about average scale.

I often struggle with structuring my source-code tree. In fact, usually, I don't complete a project without dumping the entire tree and rearranging the pieces three-four times which really takes up a lot of effort and moreover the end result does seem like a compromise.

Sometimes, I end up with over classification of source – very long tree of folders and sub-folders. At other times, I simply end up concentrating all files in a particular folder based on the larger purpose they serve and thereby leading to 'chaotic' folders in the source.

I would want to ask:

  • Are there any principles/logic/best-practices that can help me better at structuring my source tree?
  • Are there any graphical/diagrammatic techniques (for eg.: DFD in case of dataflow) that can help me visualize my source tree beforehand based on the analysis of the project?
  • What strategy to adopt to structure multi-media files-tree associated with the project?

About the bounty: I appreciate existing answers with the members sharing their own practices, however, I'd like to encourage more general and instructive answers (or resources) and more responses from the members.

Best Answer

The source tree layout should reflect the architecture; as a corollary, a well-structured architecture can lead to a well-structured source tree layout. I suggest reading up on the POSA1 Layers pattern, attempting to fit your architecture into a layered structure, then naming each of the resulting layers, and using that as a basis for your source hierarchy. Taking a common three-tier architecture as a baseline:

  • presentation/webService (present a web-service interface to our business logic)
  • logic/* (business logic modules go in here)
  • storage/sql (back-end storage APIs here - this uses a SQL interface to store to a database)
  • util/* (utility code - usable by all other layers, but that does not refer outside util, goes here)

Note that the layers do not contain code directly, but rather are strictly used to organize modules.

Within a module, I use the following sort of layout:

  • <module> (path to module directly; defines modular interface)
  • <module>/impl/<implName> (a specific implementation of the modular interface)
  • <module>/doc (Documentation for using the module)
  • <module>/tb (unit-test code for the module)

where the <module> is located in the repository according to the layer to which it belongs.

Related Topic