Tuesday, June 12, 2007

Keeping Your Code Drawers in Order

Bookmark and Share

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.

1 comment:

Michael Campbell said...

Couldn't agree more. I don't necessarily agree with the locations, or the suffixes, but the idea is so key.

We use maven, and maven does have some ideas about where stuff should go. (Much like rails is opinionated, so is maven.) So although maven's choices are not necessarily what *I* would have chosen, they're logical and "close enough" that it's a lot easier for me to mollify the tool than get all religious and have it bent to my indomitable will.

Too, any (default) maven project will look like any other, so you can hop between any company using maven and know instantly where stuff is, which is even BETTER than a company standard - a CROSS company standard!

I'm not proposing here that everyone use maven, only that it does exist and dictates where stuff goes, and this is A Good Thing(tm), in the long run.