Code Organization
From LiquidPubWiki
Contents |
Headlines about projects' code layout
Since the approach adopted for the development process is the one that characterizes the open-source community nowadays, we would like to encourage as much as possible collaboration from people who share some interest towards our projects, either by making easier for them to effectively produce code and submit it, or, simply, by facilitating operations like browsing, compilation or execution of the code.
Getting started
According to the SVN platform we are currently using to store our code, project layout is made by three directories at root's level: trunk, meaning the directory under which the main project development occurs; branches, which is a directory used to create various named branches of the main development line; tags, which is a directory of branches that are created, and perhaps destroyed, but never changed.
Sometimes, source packages or modules are randomly added to the trunk sub-directory, without a precise organization. In our case, it's better to have a structure like the one depicted in the figure below.
Src and bin will, respectively, contain the source packages and the binaries (here we talk about packages, because typically our projects have been developed in Java, but the same applies also to generic "modules").
The directory called dist will contain the project in a runnable format. For instance, if we are talking about a java web application that will run on a servlet engine like Tomcat, the file containing the deployed application (.war) must be stored here.
Doc directory embeds one directory called api, where javadocs (if we are using Java) or, in general, API specification will be included, together with a very short pdf file that describes what the user can do with the application and how to do it. We reccomend that the length of the user guide is max 2 pages.
Build instructions
Build will contain two files: the first one is the script required to compile the source files (it could be a simple Makefile rather than an XML Ant build file or a Maven one). Since we don't want the contributor to waste time understanding how to compile the project or similar issues, it is important to simplify things as much as possible. So, a file containing instructions for compiling source files should be included in the build directory as well: this has to be very short, and should be made of only a few lines of instructions with their corresponding explanations.
Subprojects build instructions
In the case you have a project that is composed by many different sub-projects, the idea is to have a "centralized" build file that, in turn, when we build up the main application, will call the different build files (that must be included in the build directory of each sub-project) used to compile the related sub-applications. This way, user doesn't have to delve into the different settings and scripts of each sub-projects, but, instead, is able to automatically manage the process from a high-level perspective.
Integration with external components
If the application requires external components (for example, it has to be deployed inside a container like JBoss, or engines like Tomcat or Hibernate), they have to be pointed out in the build instructions' file, together with instructions about the integration between those components and the project's binaries. Information concerning the configuration of external components like, for instance, the web.xml file in Tomcat should be contained in the cfg directory. Finally, external libraries used in the application (.jar files, in the Java case), have to be placed in the lib directory.
