Project Layout

One of the areas of professional software development that (I think) doesn’t get much coverage is how to layout a development area for a product on the filesystem and inside a version control package. I have been using subversion for the last four years and have always defaulted to the typical

product_name/
  - branches
  - tags
  - trunk

layout. The layout inside trunk will be dependent on product but would have at least

trunk/
  - src
  - doc
  - test

However, I’ve recently been encountering a few problems with this structure. The problems basically boil down to not being able to isolate the version control of various items generated within the product. All version control operations (eg, tags/branches) affect the entire product.

Documentation is the real bug-bear in the scenarios I have been thinking about. One could consider a scenario where a final release of a product has been shipped but a bug has been found in some documentation shipped with the product. Fixing the bug in the documentation is easy, but because the documentation resides in the same configuration area as the implementation, shipping the fix would possibly necessitate an entirely new release of the product with a new version.

I am fairly sure that what I have presented above is a problem that has been solved (potentially many times). A solution I have been toying with recently is to have multiple sub-folders for a product each of which are projects in version control in their own right. For example:

product_name/
- requirements/
  - branches
  - tags
  - trunk
- design/
  - branches
  - ...
- impl/
  - ...
- documentation/
  - ...
- test/
  - ...
- release/
  - ...

A brief explanation of these folders is:

• requirements: Stores all documents capturing the requirements for the product. Most small products won’t need detailed requirements. However, I feel that at the very least there should be some stated (and documented) vision/purpose for the product to clarify why the product is being built. Having a separate requirements area in version control allows the requirements to be version controlled just like anything else. For example, once requirements have been agreed upon between with a client, the requirements area could be tagged as “version 1.0”.

• design: Analogous to the requirements area, the design area capture all the documents related to the design of the product. Again, for a smaller product, having a completely separate area might be overkill. As I’ll mention later, there is scope for including the test planning in this design area.

• impl: This contains the code, unit test code, build scripts, and api documentation generation scripts. I would include unit test code here instead of the test area as I consider unit testing an integral part of writing the final code.

• documentation: This is the area that contains the documentation that will be shipped with the product. It is separate from the impl section so that it can be version controlled separately.

• test: This area contains formal test documentation and results. Testing is an interesting area as it is a practice that contains parts that should be conducted before implementation and after implementation. Before implementation there is the development of a test plan and a test description. After implementation there is the actual testing and the compilation of test results. I’m not yet clear how to capture these two roles. Options are to capture the test planning phase in the design area, create a separate area explicitly for test planning, or include everything in the one test area. Thinking about it now, I’d probably put the test plan in the design area and the test description in the test area along with the test results. The test area will likely also contain numerous automated test rigs that implement parts of the test description.

• release: This contains scripts to generate a final package ready for distribution and documentation of what is contained in a particular version of a product.

In addition to these core product areas, I might also add areas for storing third party dependencies (for example, libraries and build tools) and perhaps an area for reference material (coding standards, documented best practices). These things would generally be applicable to multiple products so could be stored in a central area and drawn in to each product area for easy reference. This inclusion could be conducted using svn:externals, for example.

This structure seems fairly large and unwieldy and flies in the face of extreme/agile programming. However, for products that require traceability and verification, this structure is possibly minimalistic and/or naive. I’d be really interested to hear from others on how they set up their product areas (both casually and professionally). I’d recommend anyone wishing to share to create a blog post of their own and send me a link (either in a comment or via Twitter (see the follow me link on the right)). Feel free to comment on the content of this post below.