Keeping Your Code Drawers in Order

Jeremy recently argued that you should "Put Code Where You Would Expect to Find It". He explains, "A team should strive to consistently put different types of code into separate, logical places in the structure."

I couldn't agree more, so I thought I'd echo that guidance and follow with a specific example. When organizing a project, try to establish clear conventions for what sort of code goes where and what it's named. The following represents an organization I've grown comfortable with, including a top-level folder structure and naming convention. This example is obviously applicable to the J2EE world, but a similar scenario could be described regardless of the specific technology stack.

• conf - Configuration Files
• web configuration files
• ejb descriptor files
• resource files
  
• db - Database Initialization Files
• ddl scripts
• sample data
• docs - Documentation Files
• architecture doc
• user guide
• readme
• release notes
• examples - Example Programs/Scripts
• xmlschema - XML Schema Files
  
• java - Java Source Files
  
• bo - Business Objects
• Class/File Suffix: "BO"
  
• client - Client Library
• Class/File Suffix: "client"
  
• dao - Persistence Classes: Data Access Objects
• Class/File Suffix: "DAO"
• ejb - EJB Implementation
• Class/File Suffix: EJB
• ejbi - EJB Interfaces
• Home Interface
• Class/File Suffix: "home"
• Object Interface
• Class/File Suffix: (none)
• test - automated tests
• Unit Tests
• Stress/Perf Tests
• User/System Tests
• util - utility/miscellaneous
• vo - Value Objects
• Class/File Suffix: "VO"
• webui - User Interface Source Files
• Models, Actions, Views, Forms, etc
  
• web - Web Content
• html, jsp, css, images, etc
  

This sort of consistency encourages better design, reduces defects, simplifies knowledge transfer, improves impact analysis, and reduces support and maintenance costs. It can even encourage better estimates. And the value is even greater on large-scale systems consisting of many similarly consistent sub-systems. On those types of systems, the benefits of good discipline accumulate exponentially.