CodeOrganization

The code organization at the directory level is very important. It directs a great deal of the growth of the code body, and eventually gives you the freedom to move components and packages around as the need arises, or it can get everything bogged down and lead to a collapse of flexibility for future development.

The top-down organization of the code directories needs to provide for a number of general features:

• Application Directories - Individual development areas for a specific application, where the code for the primary launching component (like 'main' in a C program or a Java class) is placed. It is where the 'index.html' or 'index.jsp' would be for web projects.
• Shared Resource Directories - This typically means libraries, headers, packages, and other resources like images, generic css files, generic java script files, and so on.
• Pre-Build Utilities - This includes anything that is involved in the development process itself, that is, writing code. Examples are code formatters, API digests and documentation, editors, and source code control systems.
• Post-Build Utilities - This includes utilities that handle manipulating and testing the results of the build. Driver scripts for testing, test data, and any associated documentation are examples.
• Centralized Utilities - Some utilities need to be built in a centralized location, and upgraded and expanded as the project expands and local needs are identified. Generally, these are scripts for the development environment and so on, but may also include utility applications that are binaries.
• Decentralized Utilities - This includes items that one would expect to find in various types of directories that are made into standard functional slots and then customized to the specifics of the needs of the directory contents. Examples are run and debug scripts that set up the proper environment for an application. If each of said scripts has a set of standard arguments, then the mystery of how to run or debug can be lessened for someone who needs to pick up development without much help or documentation. These kind of standards are usually best created by team concensus to create developer buy-in.

To consider a good example of succesful directory structure, look at the Unix file system. Directories are created so that the /bin and /usr/bin directories are where most binaries are located, and /usr/include & /usr/lib are where all the shared resources are for C development. The development environment and the general computing environment are bundled together in a harmonious way, making the development of new features for the operating system relatively simple to integrate into the existing infrastructure. The key feature of the Unix system is that the delivery environment is not very different than the development environment, making development much easier and the transition issues much smaller, provided developers stick to conventions that administrators are familiar with in the actual delivery environments. It is worth while to study the features of Unix, just to get ideas about how to structure features and their associated support files, particularly for server development of any kind.

Another point that is often not emphasized is that libraries and their headers for C/C++ development need to be delivered together, and to a set of directory conventions that provide easy use in both other libraries and applications. The conventions need to guarantee that there are no directory name collisions. Whenever a library upgrade is published, then all the dependent libraries and applications need to be built bottom-up.

The actual directory structure depends on the type of project, since C++ and C do fairly well with a fairly flat directory system, whereas Java and Web projects frequently need sub-directory systems for packages and sub-packages or logical html page areas divided by directory. These directory systems tend to grow organically, so it doesn't make much sense to try to create too many extra directories until an actual need arises.

A very Unix-style system is as follows:

<project-head>/
    scripts/
        <centralized-utility-scripts>
    bin/
        <compiled-binaries>
        <java-class-files (apps, not libs)>
        <java-jar-files (apps, not libs)>
        <perl-applications (not "utilities")>
    lib/
        <libs: .a, .so, .lib, .dll files>
        <java-jar-files (packages/libs)>
        <java-package-dirs>/
            <java-class-files or package subdirs>
        perl/
            <perl-modules (used by perl "applications")>
    include/
        <lib-dirs>/
            <published-lib-headers>
    src/
        apps/
            <application-dirs>
        libs/
            <lib-dirs>
        test/
            <test-applications>
        java/
            <java-package-dirs>
        htdocs/
            <HTML-files-and-dirs>

The scripts are in the development tree since they are frequently part of the ongoing development, and additional scripts related to specific areas of development should eventually make their way into the central script area.

This general design of directory hierarchy is good for mixed development. It is not a problem for mixed langage development. The Makefile system described in the other pages detail how it all ties together to create a single build hierarchy. The results of the build can then be delivered into a well-defined package delivery set for transition to a staging, QA, pre-production, or production environment.

Each stage the code moves away form the actual development environment, more and more of the utilities and environment familiar to a developer are stripped away. The delivery packages should include all necessary configuration and basic health-check utilites early in deployment, so administrators can get used to the idea that they are there and learn to use them.