What is the most important thing about your software application? Your feature sets? Your product verticals? Your customer customizations? Well, if you follow commonly held best practices of most web frameworks, the most important thing about your application, according to your codebase, is that your application is built from models, views, and utils.

By convention, models, views, and utils are the top level directories of 99% of modern codebases. This taxonomic breakdown by type implies a semantic value judgement; that the most important thing about your codebase is the same as your competitors, but more importantly, that it is the same as the last place most of your new hires worked. We think that this is effective organization, as it signposts the familiar to others, but actually, all it does is give up a powerful opportunity to convey information about your domain to people. Another way to say this is that the structure of your code is a form of documentation, and all the current best practice does is document that you are, in fact, using one of the same MVC frameworks that everyone has been using for 15+ years. This may be going out on a limb, but that’s not particularly valuable or surprising information to convey.

When you (or the new hire you’re training) encounter a new codebase, you are looking to understand what, why, and how, in that order. What does it do, why does it do that, and how does it make it happen. You may think how is first, but encapsulation is literally all about making how last, and I don’t think it’s controversial to say encapsulation is good (well, that’s a different post at least…). The models views utils structure puts how first, what second, and doesn’t even touch on why, but why is really the thing that lets you be effective in building new features. That structure is putting datatypes and design patterns as the core organizing principle of your system, but those shouldn’t be the core organizing principle of any system except for exemplars in school or Stack Overflow.

In summary, your code structure is one of the first pieces of documentation about what your application is. Treat it that way, and resist the urge to set the taxonomy of your system by datatype and design pattern.