How to organize source code? Learn from Java.

Since most HDLs do not force you to use a specific directory structure in your projects, each organization is left with the burden to devise its own conventions. This post describes directory and file naming conventions, learned from the Java programming language.

Basic structure

The basic design unit in Java is the Java Class. Each Java class has its own file, with the file name identical to the class name, and the extentions .java. Java classes are further organized in Java packages, which are visible in the source code. Java packages correspond directly to the directory structure of a Java project. The convention for package naming is that package names correspond to the domain name of the organization that provides the package.

An trivial example will make things clear. I've created a trivial hello-world example in the folder c:\projectdir\. The example consists of a single class HelloWorld (naming convention in Java is that class names start with a capital, and use CamelCase) in the package com.sigasi.example.

The only file we need for this project is:

c:\projectdir\com\sigasi\example\HelloWorld.java</pre>

When several subprojects are aggregated, each project has to conform to the directory structure:

The only thing a Java tool needs to know to process this aggregated project, is the root directories of each subproject. In this case c:\projectdir1 and c:\projectdir1. This way, you do not have to list which files should be included or excluded in your build. The convention is simple: all files will be compiled.

Note that package names start with internet domain names, in inverse order (here: sigasi.com). This avoids name clashes, since each organization can create its own package structure within its own domain.

Improvement: source and binary dirs

When compiling the previous examples with a standard Java tool, the binaries (class files, in Java-speak) will be in the same directory as the source files: c:\projectdir1\com\sigasi\reusable\HelloUtils.java

This is not desirable. First, when you share the source files (e.g. in a version control system, or a tarball) you do not want the binaries. Conversely when shipping the binaries to a customer, you probably do not want them to see your source code.

Most Java projects nowadays split the source and binary files in a separate directory, typically src and bin: