source code trees: wide or deep

Question

After writing a few python appengine apps I find myself torn between two approaches to organizing my source code tree: wide or deep.

For concreteness, consider an internal application for a small consulting shop to manage business operations like contact management, project tracking & reporting, and employee management. The application might use key entities like: Company, Users, Contacts, Customers, Projects, Timesheets, etc. Without going into details, one can imagine that these models are cross-cutting across the functions of the website. This likely means there is some coupling.

In this example, is it preferable to organize in a deep-manner, e.g.:

models/
   people.py
   accounting.py
   projects.py
   foo.py
controllers/
   reporting.py
   employeeops.py
   accounting.py
   crm.py
views/
   ...

or a wide-manner, e.g., by "application":

people/
   models/
   views/
   controllers/
contact-mgmt/
   models/
   views/
   controllers/
time-tracking/
   models/
   views/
   controllers/
project-reporting/
   models/
   views/
   controllers/

I know all design involves trade-offs, so when responding can you indicate your preference and some reasoning (e.g., assumptions, modulating concerns, framework limits, scalability issues, code maintenance considerations, impact of development team structure, etc.).

Answer 1

Caveat: I haven't worked in python specifically. Having said that...

Wide, and I'll tell you why: It never hurts to be able to remove things quickly. In my career I am often asked to add things and given a relatively reasonable schedule on which to do it, but when something needs to be removed, the request almost never comes with impact analysis or time to mess around. When you break things out by major functional modules, you usually end up with a much less coupled design. It can be a real pain in the ass, but for those times when you absolutely have to get the work order module turned off by the end of the week, it is a life saver.

Answer 2

Too deep a folder structure makes it confusing. Too wide makes it confusing. I prefer to keep a balance between them. On the project I'm working on, we had no idea what we'd need, so we didn't prematurely create a massive folder structure. After all, we only started with 5 files, so we didn't really have a need for a folder structure. As the project got bigger, we organised things to keep it neat as we went; no folders having more than 10 files, grouping things into folders clearly. It would take a few minutes to move it all around. Now we have well over a hundred files, and it's always clear where things are. My recommendation is to do similar - keep it neat, don't go too far with either depth or width, or you'll over-complicate things.

Answer 3

In your case I think the "wide" model is better. You should try to create your apps so they reusable even if you don't plan to reuse them anywhere as this will encourage looser coupling bewteen different apps and make maintenance easier in the long run.

Answer 4

Actually I prefer a mix. Software is divided into Horizontal and Vertical Components.
Horizontal components are reusable across all modules and represent common code to be reused that is not application specific, instead is architecture specific.
So I have folders for common Utilities, Frameworks, reusable infrastructure libraries, such as Persistence, Communications, Security, logging etc...

Vertical components are the individual Use Cases. For each use case I have a folder that has UI, Server and under UI I have views and controllers. The model is often shared between the two.

If your project is really large then you probably have different areas of responsibility, such as Inventory Control, Sales, Contact management, Reporting etc ... Add these to your folder structure and put the use cases that apply under them.

Feel free if there is any reuse to move any components up the tree.