Project Design: Directory Structure

I’m about to rework the directory structure of one of our projects. After careful 
 preparation, we’ll do a major refactoring of the existing layout, which no longer meets the project’s needs. 
 Changing a project’s directory structure is always painful, for several reasons.

• You have to change the source repository layout, for example in CVS.
• Everyone has to synchronize with that change.
• You have to test the change at the appropriate level, with unit tests for the code and validity checks for the build scripts, for instance.

These are substantial reasons to approach the job with surgical precision. 
 Sometimes the cut is so radical that you have to swap the scalpel for a cleaver. It’s better 
 to avoid these problems at the start of the project. Based on my experience with several larger projects, at least by my standards, 
 I’ve laid out a few steps for creating a stable project 
directory structure.

Design the project layout before the first commit

Most project layouts draw on prior experience and established habits. That experience can come 
 from a previous project, a prototype, or an entirely different project 
 whose structure inspires you. In short, you have a rough idea of what the directory 
 structure should look like. The worst thing you can do is rush to synchronize
 your ideas with the source repository.

I suggest documenting the layout, adding more detailed comments and building 
 a prototype of it.

Documenting the layout

\root directory
	|
	|-db
	|
	|-doc
	|	|-javadoc
	|	|-project
	|    	
	|-config	
	|	|-hibernate
	|     	| 	|-app    	
	|	|		|*.hbm.xml

Directory list and descriptions

As you can see, all we need to connect the layout and its descriptions is HTML. A layout documented this way is a foundation
 you can build on. The proposed layout should match the source repository. You can also document directories 
 outside the repository that are directly related to the project. These might include a directory 
 for unit test results or a build directory.

Validating the layout

Choose a small group of three or four people and show them the proposed layout. The point is to catch any mistakes and 
 extend the layout, since you won’t always spot every particular requirement. Document all changes and create a model of the layout. 
 Now you have a starting point. Remember that the document describing the directory structure belongs in 
 the project documentation, specifically in the section for developers.

Set rules and appoint a maintainer

Appoint one project member as the maintainer responsible for changes to the project layout. Set boundaries for 
 that responsibility. For example, only the maintainer can change the top-level structure. These boundaries 
 are usually difficult to set. One rule that can help is to have the maintainer sign off on every change to a subsection. Such a change 
 doesn’t affect other parts of the project, such as build scripts or APIs. The maintainer’s job is to inform everyone of all changes, make them and document them. 
 All change requests also go through the maintainer.

Put the layout into use

The maintainer creates the prepared layout in the source repository and development can get under way. Of course, during development you’ll find you need 
 to extend the existing layout or make small adjustments. The setup makes those changes less painful.