“A place for everything and everything in its place” — thoughts on organizing source code by type

I’ll start this article with three short excerpts from the book “Things I’ve never heard at a software consultant firm”:

Project manager: “Our client wants you to work on all concrete implementations.”
Developer: “Great — they’re here in the ‘Classes’ namespace so it’s easy for me to work on all of them at once.”


Project manager: “We need to work on all our interfaces.”
Developer: “How lucky that they’re all stuffed into the ‘Interfaces’ project.”


Developer: “I’m really glad this solution is organized by type rather than by logical groupings of related code. This way I can enjoy a cruise through the entire codebase every time I work on a feature.”

Why is organizing code by type bad?

The decision of where to put code greatly influences the development workflow and how the solution architecture evolves over time.

The chance of creating a big ball of mud is much higher when using e.g. a single bucket for all concrete implementations; it leads to spaghetti code because all classes are seemingly closely related, and hence should seemingly be allowed to reference one another.

Simply put, having a namespace or project called “Interfaces” filled with every single interface in the entire solution communicates absolutely nothing about which of — and how — those interfaces are supposed to work together. The same is true for classes, enumerations, functions and whatever else your programming language of choice has to offer.

At best, organizing code by type violates the principle of least astonishment. At worst, organizing code by type will leave the development team digging through the codebase again and again in search of the pieces making up any given feature, and increases the risk of breaking feature encapsulation.

What’s a better alternative?

Start off by reading about various software architecture methodologies and make an opinionated choice fitting the project in question; revisit your choices regularly to avoid the Golden Hammer pit.

For most of the web projects I’ve worked on, I’ve advocated organizing code into modules/components. Fleshing out components has become the natural extension of class level OOD brought to bear on a larger scale for me. Hence my answer is:

Organize the code in your solution into expressive components, just like you would organize functions and functionality into expressive interfaces and classes.

The above is far from an exact science and quite honestly based on gut feelings developed over the years. I’ve tried to examplify the differences between “type based source code placement” and component based architecture in the following simplistic example which still should make the main point clear — organizing code purely by type is bad.

Example

Let’s start off with a dialog that actually has a chance of taking place between a PM and a dev:

Project manager: “Our client want’s to integrate to a new payment provider.”
Developer: “Great, I’ll get right on working with the payment provider related code.”

You’ve worked on the project for some time and seem to remember there’s both classes and interfaces related to the existing payment provider integrations.

Which source code structure gives you the best vantage point for your task?

Classes
    Adipiscing
    Amet
    Arcu
    BitPayProvider
    Consectetuer
    Consequat
    Cras
    Diam
    DibsProvider
    Dignissim
    Dolor
    Donec
    Dui
    Eros
    Euismod
    Facilisis
    Felis
    Fermentum
    Ipsum
    Justo
    Lorem
    Malesuada
    Mauris
    Morbi
    Nec
    Non
    Nullam
    Odio
    Orci
    Ornare
    PayPalProvider
    Pede
    Pellentesque
    Pharetra
    Posuere
    Quisque
    Semper
    Suscipit
    Suspendisse
    Turpis
    Ultricies
    Viverra
    Volutpat
    
Common
    [...]
    
Enums
    [...]
    
Interfaces
    IAdipiscing
    IArcu
    IConsectetuer
    IFacilisis
    IFelis
    IMalesuada
    IMattis
    IMorbi
    INec
    INibh
    IOrnare
    IPaymentProvider
    IPlacerat
    IPorttitor
    IPosuere
    IQuis
    ISit
    IUrna
    IVolutpat
        
Logging
    [...]

Security
    [...]

Tests
    [...]
Common
    [...]
    
Forms 
    [...]
    
Logging
    [...]
    
Payment
    BitPayProvider
    DibsProvider
    Euismod
    Facilisis
    IPaymentProvider
    PayPalProvider
    Quisque
    
Security
    [...]
    
ShoppingCart
    [...]

Tests
    [...]

Who’s organizing code by type?

The tendency to organize code by type is much more prevalent in small to medium sized in-house development teams than in software consultancy companies.

This statement is based on a decade working on and/or reviewing code from 10+ in-house teams and 20+ consultancy firms.

References

The following is an incomplete list of companies whose code I’ve reviewed, worked on, worked with or for some other reason have had my hands and/or eyes on. It’s not a list of companies who organize code by type.

More career info available here.

One thought on ““A place for everything and everything in its place” — thoughts on organizing source code by type

  1. I totally agree, well said. I hate it when it’s organized by type and when it continues to the Sitecore structure then ir’s really hard to work with

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s